5/22 update: This post generated a lot of controversy, and I believe part of the controversy could have been avoided if I had articulated my ideas better. I've gone through and updated parts of this post by adding notes. My additions appear in green. The previous title was "Structured Authoring Versus the Web". However, of course the web uses structured authoring. Every web form in this post -- the title, body, category, tag, date, featur...
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, because that switches us right back into the book paradigm. There's probably not an exact way to determine topic length, becaus...
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 topics are a best practice anyway: Most users I have written for have no desire to read or skim through a long page of...
In many companies, documentation and support are different kingdoms, with their own tools, processes, and workflow. As such, the content usually remains separate. When users need information, they have to search different content repositories (that is, if support even even makes its content accessible to users at all). It seems natural that combining the search scope to include both support content and documentation would create a winning...
I owe a lot to James Naismith, the man who invented basketball. In case you're unfamiliar with the origin of basketball, basketball is actually an evolution of running. Naismith was an exercise coach who tried making exercise more fun by placing peach baskets at both ends of a gym. Previously, people would run around or do other exercises with no explicit purpose. Now they would try to put a soccer ball in a peach basket. In other words, ...
For an updated post on this topic, see DITA's output does not require you to separate tasks from concepts. 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 into a l...
I've recently fallen in love with a site called Code Academy, which juxtaposes a real-time programming console with instructions and activities. It's the most hands-on, interactive site I've come across, and I want to someday model my own help to be like it. Here are a few key points: Users learn by doing. Each concept has an associated activity with it that reinforces the concept through the activity. The concepts have to be somewhat si...
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 creating both code and prose. You have a passion for the web and its ability to solv...
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. Blogging makes writing so much fun, in fact, that about 2 million new blog posts are written each da...
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 had scores of bloggers inserting the badge on their sites, displaying MindTouch and linking back t...
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 and must be cleaned. Our computer desktop gets cluttered and must be ordered. Broken eggs d...
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 brackets with their character symbol equivalents (< and > for less tha...
In my previous post, I wrote about how handy collapsing and expanding sections can be. Although there are several plugins that enable this functionality, it's pretty easy to create this functionality yourself from scratch. JSfiddle.net is a neat site that lets you play around with JavaScript, separating out the HTML, CSS, JavaScript, and result into their own quadrant on the page. I created a "fiddle" showing the HTML, CSS, and JavaScript...
After my post on Organizing Page-Level Content, a couple of people asked me about the usability of collapsible sections, also known as content toggles or dropdown hotspots. These are sections that are collapsed upon initial display and then expand when clicked. You can implement collapsible sections in several ways. In Flare, you can insert drop-down hotspots from a quick button on the ribbon. In Drupal, you can use the Collapse Text modu...
I have a few bad habits I'd like to break. One of those habits is crashing on Friday nights. After working all week, I tend to crash around 8pm and let my brain cells go dormant for a few hours watching mindless television. When the morning comes, I open my sleepy eyes and wonder why I wasted all that time the night before. If I could get those hours back, I certainly wouldn't spend them watching TV. Productivity is a perennial topic for ...
