One challenge I’ve recently been considering is how to handle content re-use on a web content management system, such as Drupal, Joomla, WordPress, or some other web platform. Let’s say you’re writing about ACME widgets and have three different audiences: ACME developers, ACME sales people, and ACME administrators. All your help content is hosted on Continue Reading »
I recently listened to the Scriptorium webinar on the State of Tech Comm, which I found well-worth my time. One theme I keep hearing is a trend toward structured authoring. In Scott Abel‘s benchmarking survey (which the webinar uses as a starting point), Scott found that 44% of companies are using structured XML content, with Continue Reading »
In my previous post, Do Short Topics Make Information More Findable, I argued that shorter topics make it more difficult for users to find information. I ended the post by saying that topics that are more substantial make content more findable. But how big should the topics be? Obviously not the length of a book, Continue Reading »
In my last post, which now has more than 80 comments, I noted that authoring with DITA seemed to encourage authors to create a lot of little topics. DITA experts chimed in to say DITA doesn’t constrain users with topic length in their outputs — authors can combine topics as needed. However, one commenter noted that short Continue Reading »
I’m currently exploring the possibility of authoring content in DITA (using a tool such as easyDITA), publishing to an HTML web help output (through the DITA Open Toolkit), and then importing the output into Drupal (through some Python scripts someone has created). This sounds like a good workflow to me, but I’ve kind of run Continue Reading »
Anne Gentle, one of my favorite bloggers, recently wrote about the diverse backgrounds of the technical writers around her — see Developers, Writers, and First Jobs. In her post, she included a job description for a “Microsoft Programming Writer.” It’s kind of a mind-blowing description. Here’s what Microsoft is apparently looking for: You are comfortable Continue Reading »
A couple of weeks ago, I wrote about Gamifying Chores. While chores are easy to quantify and measure, activities such as writing have a different dynamic. How do you gamify an activity that has so many complicated facets, purposes, and forms? Blogging is one way to gamify writing. Blogging introduces game elements to make writing more fun. Continue Reading »
MindTouch recently released their report about the most influential people in techcomm, and I was happy to rank so high. I’ve had varying reactions to this report for the past several years. The first year MindTouch released the report (2010), I thought it was an ingenious marketing tactic. Within days after the initial release, the company Continue Reading »
Why is it that writing can start out clear and organized, with a coherent logic and order, but then progress toward fragmentation, disarray, and messiness? How do you move from an ordered content system to an unordered content system? The movement towards disorganization describes the natural direction of many things. Our houses get messy each week Continue Reading »
If you’re integrating code examples into your technical documentation, a couple of tools can help with this. If you have an online output, you can use Code Prettify (see its Drupal version or WordPress version or regular HTML page version). This module/plugin applies syntax highlighting to your code so that it’s more readable. I usually replace the angle Continue Reading »