Search results

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

Series: Findability / organizing content

by Tom Johnson on Jun 3, 2010
categories: findability • technical-writing • wikis

  1. 1.0 New Series: Organizing Content [Organizing Content 1]
  2. 1.2 Introducing Project Swordfish [Organizing Content 2]
  3. 1.3 Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]
  4. 1.4 Imposing Order Versus Observing Order [Organizing Content 4]
  5. 1.5 Topic-Based, Hierarchical Navigation [Organizing Content 5]
  6. 1.55 25 Facets for Navigation [Organizing Content 5]
  7. 1.6 Faceted Classification, Faceted Search [Organizing Content 6]
  8. 1.7 Implementing Faceted Classification/Search with a Help Authoring Tool [Organizing Content 7]
  9. 1.8 Second-Level Faceted Navigation [Organizing Content 8]
  10. 1.9 Browse Versus Search: Stumbling into the Unknown Unknown [Organizing Content 9]
  11. 2.0 Figuring Out Search Algorithms [Organizing Content 10]
  12. 2.1 Search Engine Optimizing Your Help Content for Google [Organizing Content 11]
  13. 2.2 → From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]
  14. 2.3 Using Mediawiki Templates to Organize Content [Organizing Content 13]
  15. 2.4 The Semantic Web and Content Findability: Interview with Patrick Warren [Organizing Content 14]
  16. 2.5 Faulty Assumptions About the Scope of Help Content? [Organizing Content 15]
  17. 2.6 Can Blogs Work as a Web Platform for Help? [Organizing Content 16]
  18. 2.7 Organizing Content as Story [Organizing Content #17]
  19. 2.8 Separating Basic from Advanced Topics: How Twitter Organizes Their Help [Organizing Content #18]
  20. 2.9 Emergence [Organizing Content #19]
  21. 3.0 Relying on the Wisdom of the Crowds with Help Authoring [Organizing Content #20]
  22. 3.1 Principles for Organizing Print Material [Organizing Content #21]
  23. 3.2 The Technical Writer as an Outsider: How Ambitious Are You? [Organizing Content #22]
  24. 3.3 The Interface Is Text [Organizing Content #23]
  25. 3.4 Best Practices for Writing Interface Text [Organizing Content #24]
  26. 3.5 Organizing for Learnability [Organizing Content #25]
  27. 3.6 Why Learning Software Is So Hard, and Organizing Content into Levels [Organizing Content #26]
  28. 3.7 Is Rhetoric Relevant? Considering the "Message in Context" [Organizing Content #27]
  29. 3.8 Organizing Content for Constructivist Learning [Organizing Content #28]
  30. 3.9 Eight Defining Questions that Shape Content Organization [Organizing Content #29]
  31. 4.0 Why Help Content Fails and #contentstrategy

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 Shannon 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.

naKtaS-7Qq4

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:

Contents
Categories
Parent Categories
Content
Articles
Main topic classifications | Fundamental
Nature | Phenomena | Fundamental | Main topic classifications
Life | Natural sciences
Animals | Biology
Eukaryotes | Zoology
Animals | Phyla
Chordates
Vertebrates | Tetrapods | Synapsids
Mammals
Primates
Apes
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.

  1. 1.0 New Series: Organizing Content [Organizing Content 1]
  2. 1.2 Introducing Project Swordfish [Organizing Content 2]
  3. 1.3 Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]
  4. 1.4 Imposing Order Versus Observing Order [Organizing Content 4]
  5. 1.5 Topic-Based, Hierarchical Navigation [Organizing Content 5]
  6. 1.55 25 Facets for Navigation [Organizing Content 5]
  7. 1.6 Faceted Classification, Faceted Search [Organizing Content 6]
  8. 1.7 Implementing Faceted Classification/Search with a Help Authoring Tool [Organizing Content 7]
  9. 1.8 Second-Level Faceted Navigation [Organizing Content 8]
  10. 1.9 Browse Versus Search: Stumbling into the Unknown Unknown [Organizing Content 9]
  11. 2.0 Figuring Out Search Algorithms [Organizing Content 10]
  12. 2.1 Search Engine Optimizing Your Help Content for Google [Organizing Content 11]
  13. 2.2 → From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]
  14. 2.3 Using Mediawiki Templates to Organize Content [Organizing Content 13]
  15. 2.4 The Semantic Web and Content Findability: Interview with Patrick Warren [Organizing Content 14]
  16. 2.5 Faulty Assumptions About the Scope of Help Content? [Organizing Content 15]
  17. 2.6 Can Blogs Work as a Web Platform for Help? [Organizing Content 16]
  18. 2.7 Organizing Content as Story [Organizing Content #17]
  19. 2.8 Separating Basic from Advanced Topics: How Twitter Organizes Their Help [Organizing Content #18]
  20. 2.9 Emergence [Organizing Content #19]
  21. 3.0 Relying on the Wisdom of the Crowds with Help Authoring [Organizing Content #20]
  22. 3.1 Principles for Organizing Print Material [Organizing Content #21]
  23. 3.2 The Technical Writer as an Outsider: How Ambitious Are You? [Organizing Content #22]
  24. 3.3 The Interface Is Text [Organizing Content #23]
  25. 3.4 Best Practices for Writing Interface Text [Organizing Content #24]
  26. 3.5 Organizing for Learnability [Organizing Content #25]
  27. 3.6 Why Learning Software Is So Hard, and Organizing Content into Levels [Organizing Content #26]
  28. 3.7 Is Rhetoric Relevant? Considering the "Message in Context" [Organizing Content #27]
  29. 3.8 Organizing Content for Constructivist Learning [Organizing Content #28]
  30. 3.9 Eight Defining Questions that Shape Content Organization [Organizing Content #29]
  31. 4.0 Why Help Content Fails and #contentstrategy

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson