From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]

Yes, I am continuing this series on Organizing Content, so if you are tired of it, check back in a while. My goal is to reach 100 posts on the topic.

An Electricity Fast

First, a brief bit of news. All the lights in my house are off because Jane wants to do an electricity fast. It’s a Thoreauvian experiment to see what you gain when you give something up. For the past couple of days I’ve been moving about with a candle, or staring at a computer screen in total darkness. I can’t cut off all electricity because that would be a little too extreme — food in the refrigerator would go bad, my side job with WordPress consulting would tank, my blog would slow to a halt. We made agreements about certain allowances. But by merely turning off the lights, it’s amazing how this puts you into a rhythm (or would if I were to turn the computer off).

Time to Take the HAT Off

Back to the topic at hand. In my last post, as I diligently looked into SEO and the importance of help’s visibility in Google, I found that help authoring tools have poor SEO. This is partly due to frames, partly due to the fact that few users will link to help content, and also because HAT code isn’t architected in an optimal way for the web.

If we plan to keep step with the web, we have to use a web platform. As a general trend, I think help authoring tools are going to fade because (a) they do a terrible job at SEO, (b) help authoring tools are poor at collaborative authoring, (c) help authoring tools fail at social media and interactivity, (d) help authoring tools don’t leverage the plugins and extensions of web platforms such as WordPress, Drupal, and Mediawiki, and (e) help authoring tools are expensive compared to web tools.

Additionally, the importance of single sourcing the long print manual is becoming less of a demand (have you handed someone a 100+page manual lately that someone accepted with eagerness? ) I predict that in several years time, we’ll see a major shift towards web-based tools in tech comm, especially wikis.

As a final nail in the coffin, check out this video on social media. It argues that social media presents the biggest shift since the Industrial Revolution.

After watching this video, it seems unlikely that the traditional HAT will be the default tool for software user instruction in a few years.

On to Wikis

Until now, I’ve explored ways to organize content with the assumption that we’re using a help authoring tool. Now I would like to shift to the same discussion but with a web-based platform in mind: the wiki.

Wikis pose serious challenges when it comes to content organization, because all you have are essentially links. In describing different information architecture patterns, Donna Spencer calls wikis a flat model. With wikis, you often don’t have a table of contents feature to organize your topics. You have a page that links to another page that links to another page ad nauseum.

Which Wiki?

Given that there are more than 100 different wiki platforms, it will be difficult to generalize about wikis, because surely some wiki out there (for example, Confluence) probably has a fine TOC feature that collapses and expands. Other wikis may not have flat structures (for example, SharePoint’s wiki system, which provides you with metadata and views). But I will take as my example the quintessential wiki plaform: Mediawiki. (Wikipedia uses Mediawiki as its wiki engine, in case you didn’t know.)

A Maze of Chaos

A few years ago, at a Doc Train West conference, I interviewed someone who asked to remain anonymous. It’s the only anonymous podcast interview I ever conducted (out of about 130 podcasts). The next day, the person asked me to not publish it. Why? The conference had a lot of sessions about wikis. The interviewee explained that at her work, they had created a wiki. It started out okay, but it soon degenerated into a maze of chaos. It had become an embarrassment, an impossible black hole of content. She was cautioning against wikis.

Part of the problem with organizing content on wikis is lack of control. As soon as wikis become a collaborative effort, with multiple authors, the organization becomes much more challenging and is likely to suffer from inconsistency and chaos. I don’t know if this is inherent in collaborative authoring projects, or if it’s inherent in the wiki architecture, but eventually wikis become so disorganized that search becomes the only method of navigation.

Case in point, check out the WordPress Codex. If you have a body of information this size, there’s no clear way to organize it. You end up with links that you can kind of group together, into Getting Started, Design and Layout, Advanced Topics. But then you also have general groupings under vague topics like Working with WordPress and About WordPress. There’s no clear path through the content.

Wiki Categories

One way to organize wiki content on Mediawiki is through categories. Many people reading Mediawiki wikis don’t realize this, but each page is usually tagged with a category. For example, the Wikipedia page on Technical Communication is labeled with the category Technical communication (scroll to the bottom to see it).

The category label appears at the bottom

The category label appears at the bottom

Categories on Mediawiki work just like categories on WordPress, except that the method for adding them is less intuitive. Somewhere on the page, you just add the text [[Category:Technical Communication]]. This creates a category link that will pull together all other Wikipedia pages tagged with this same category, as shown in the image below:

All topics on technical communication on wikipedia

All topics in the Technical communication category on Wikipedia

This method of content organization isn’t bad, except that the category link is buried in the page’s footer and is practically invisible. Some Mediawiki skins display the category link more prominently.

Still the Same Challenges

Despite this system of categories, you still run into the same issues of content organization. If you click the Discussion tab for this Technical communication category page, you see the following exchange between users:

Does Category:Specification languages really belong in this category?—iFaqeer (Talk to me!) 04:25, Nov 30, 2004 (UTC)

I’m not totally sure. I’m still trying to get my head around how this category system is supposed to work. I think there’s definitely some connection between technical communication and spec languages (like UML) but I don’t know whether it belongs as a subcategory. It certainly looks strange to be all by itself. If you’d like to remove it, I wouldn’t object. —LeeHunter 23:06, 30 Nov 2004 (UTC)

I don’t think it needs to be a subcategory. Perhaps it belongs as a link from an article discussing how some technical writers deal with them in their day to day jobs. Maybe as part of the main Technical communication article??–GeoffPurchase 04:33, 2004 Dec 1 (UTC). The contents of Specification language don’t quite co-relate with the contents of that category. Does it? I mean, do they? The category seems to list what I would call “mark-up languages” while the definition is for a kind of programming language (which might be a superset of what is in the category). If I am right, the latter is definitely TC-related; the former is only marginally so.

I am not very well-informed on either of the two areas my confusion spans, so I would like someone else to chime in. And the reason I keep posting this here is that it’s kinda lonely at Category talk:Specification languages.—iFaqeer (Talk to me!) 05:12, Dec 1, 2004 (UTC)

Does specification language fit into the Technical communication category? Maybe. I’m not even sure what a specification language is. Strangely, when I looked at this more closely, specification language didn’t make it into the Technical Communication category. But Specification did.

Categories and Subcategories

The fun doesn’t stop here. Each category can also have subcategories. Or looking at it from another perpsective, each category can also be grouped under a parent category. When you’re looking at a category, such as the Technical Communication category, scroll to the bottom to see which parent category it belongs to. You’ll see that Technical Communication is categorized under Written Communication | Communication | Technology. Technical Communication is a subcategory for these categories.

Larger categories that Technical communication is grouped under

Larger categories that Technical communication is grouped under

If you click these parent categories, you’ll see that they’re also grouped into higher-level parent categories, namely, Human skills | Information systems | Language. Human Skills is a subcategory of Skills | Humans | Human behavior. Humans is a subcategory under Anthropology and Hominina. Hominina is a subcategory of Apes. Apes is a subcategory under Primates. Primates under Mammals. Mammals under Vertebrates | Tetrapods | Synapsids.

Vertegrates is a subcategory under Chordates. Chordates is a subcategory under Animals | Phyla. Animals is a subcategory of Life | Natural Sciences. Life is a subcategory of Nature | Phenomena | Fundamental | Main topic classifications. Nature is a subcategory of Main topic classifications | Fundamental. Fundamental is a subcategory of Articles, and then it goes to Content > Parent Categories > Categories > and Contents.

The exact taxonomy depends on how you climb up the topics. Like a pedigree chart of ancestors, you can take multiple paths. But here’s the general layout of categories and subcategories. I bolded the path I took to climb up to the highest level of categorization:

Parent Categories

Main topic classifications | Fundamental
Nature | Phenomena | Fundamental | Main topic classifications
Life | Natural sciences
Animals | Biology
Eukaryotes | Zoology
Animals | Phyla
Vertebrates | Tetrapods | Synapsids

Anthropology | Hominina
Skills | Humans | Human behavior
Human skills | Information systems | Language
Writing / Communication
Written communication / Communication / Technology
Technical Communication

I don’t know about you, but I feel a special pride in the way this plays out, and how in just a few levels, you move from Technical Communication to Chordates. Maybe this is why the Category label appears at the bottom of the article and search appears at the top.

At the Highest Level, Categories Fail

It’s especially interesting to look at categories at the highest level: Contents.

One of the highest levels of categorization on Wikipedia

One of the highest levels of categorization on Wikipedia

At this level, content is grouped into such general categories that it’s almost useless — categories by status, by topic, by function, by association, by type. If you were starting out here, would you ever drill down into Technical communication? It would take a miracle. But at the lower, more specific level, the category model does seem useful.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Greg DeVore

    One of the problems with wikis is the lack of constraints. Igor Stravinsky said:

    “The more constraints one imposes, the more one frees one’s self. And the arbitrariness of the constraint serves only to obtain precision of execution.”

    Limitless nesting and categorization only creates confusion and for the author and the end user. We advise our customers to set some simple rules about their documentation and follow them. With those rules in place many decisions are already made which means more time can be spent creating than planning.

  • James Wynn

    Consistency doesn’t need to be a problem with collaborative documentation. It is simply that the team employing this medium cannot dispense with a technical writer, to review, edit, properly format, and organize the data.

    When I created wiki-based System Architecture documents and user guides, I did the following:

    * I created templates for starting new pages with consideration of who would be updating the pages and who the most common readers would be.

    * I created Table of Contents pages as initial page of each documentation project.

    * I assigned the job of tagging to myself.

    * I ensured I was notified whenever a page was updated so I could review the changes.

    When people think of wiki documentation, they typically think of Mediawiki. But the free wikis are almost certainly not the best choice. If the client is cash poor, fine (temporarily), but if they can afford a technical writer, they can probably spring for $15K for a decent app.

    Any wiki app you choose should have the following:

    * A WYSIWYG editing interface. If it is only easy for a SME to enter basic text, then that’s all they’ll do. This also allow you to make table templates that can be easily copied and pasted between pages.

    * An easy method for readers to enter comments that you can choose to hide or reveal based on privileges. (Although it is good to let any user enter a comment on a page, you probably don’t want casual or anonymous readers to SEE all the comments.

    A good collaborative application that I’ve used is Traction Teampage. It even has a free version that includes up to 5 logins, and 5 documentation projects. Five logins is actually plenty to get started on a basic documentation project, since the developers can share a login if they have to.

    • Gina Fevrier


      Thanks for posting this. I hadn’t heard about Traction TeamPage, and at first glance, it looks pretty good.


  • techcommdood

    HATs will be around for a very long time. I’m willing to wager that they are not frozen in time and will shift with demand. Right now I don’t see a huge demand for SEO optimized social media-friendly online Help, but that may change over time. Just as tools have morphed from basic control applications that produce .doc and .hlp output, they can morph in other directions too. Are they currently poised to handle your predictions? No. Then again, I don’t think there are too many people using RoboHelp v.1 to produce context-sensitive WebHelp. 😉

  • Gina Fevrier

    Hi Tom,

    The only suitable commercial (closed) wikis we’ve seen or tried for external user documentation are Confluence and Mindtouch, in a large part due to the table of contents feature. We’re also looking at EditMe, which the STC is using for their Body of Knowledge project. Confluence is expensive ($24K per year for 2K+ users with 1st year of support), but Mindtouch starts at $30K/year plus support. Both have very good features for user docs.

    Please see my blog at where I’m posting our experiences with Confluence.


    • Tom Johnson

      Gina, thanks for commenting. I enjoyed reading about your experiences implementing Confluence. It’s interesting to see the transition from a help authoring tool to a wiki, and the reactions from the customers. I didn’t realize Confluence was so expensive. I think it’s less expensive for non-profits, though.

  • Bonnie

    I’m at the very beginning of designing a wiki for the purpose of sharing a knowledge base among a group of people who work in a particular area of law. I’m doing okay technically, but I’m confused conceptually about the best way to structure this. One the one hand, the thing can be a giant page divided into a hierarchy of sections each of which is editable. Or each section could be a single page, with then advantage I perceive as permitting discussion of each individual topic. But if I choose a lot of small page, how can I generate a TOC or index that gives the user a sense of where he/she is in the overall structure at any given time? Google has not really been my friend here. Thanks to anyone who can point me someplace with guidance on how to think about this.

  • wallet ninja multitool

    First off I want to say wonderful blog! I had a quick question in which I’d like to ask if you don’t mind.

    I was curious to find out how you center yourself and clear
    your mind before writing. I’ve had a difficult time clearing my mind in getting my thoughts out there.
    I do take pleasure in writing however it just seems like
    the first 10 to 15 minutes are wasted simply just trying to figure out how to begin. Any ideas or tips?