Can Blogs Work as a Web Platform for Help? [Organizing Content 16]

If you know me, you know that I love WordPress. Which is why this post may seem a bit odd to you. Lately I have been exploring BlogEngine as a possible web platform for help.

BlogEngine? That little startup blog platform that runs on .NET and Windows? Yes, I will explain in a moment. But first a quick recap on where we are in the Organizing Content series.

We left off at 15, and there are nearly 20 comments on that post alone. In that post, I asked what the scope of help content should be. Should you document everything, adding topic after topic based on every question users ask, on every incident logged at the support desk, and so on? Following such a model will result in more challenges with content organization than merely documenting the basics.

In previous posts, I also highlighted the shortcomings of help authoring tools (HATs). Not only is their search feature usually primitive and hard to customize, content produced by HATs is less visible on the web. I noted that wikis are one platform that seems particularly suited to help authoring in a web environment. And then I explored ways to organize content on Mediawiki.

But what if you’re in a corporate environment that restricts you from using PHP and MySQL based tools, such as Mediawiki? What if your IT department is a Microsoft shop that requires you to use ASP and .NET solutions that can run on a Windows server? Yes, I’m taking about my situation (at least for some internal projects).

After writing those posts, I wanted to explore ways to deliver help through a web format compatible with Windows server. All of my first choices — Mediawiki, Drupal, WordPress, Joomla — rely on PHP and usually MySQL. This means they are “off the menu,” as our enterprise architects put it.

As I was lamenting the lack of WordPress one week to our application systems engineers, one of them asked if I had ever used BlogEngine, which is similar to WordPress but runs on .NET rather than PHP. At first I resisted using any other blog platform besides WordPress, because WordPress literally has 10,000 plugins and themes, which make it one of the most robust blogging platforms available.

But the more I thought about it, the more open minded I became. The engineer (who was, I should add, a .NET developer) noted that some even say BlogEngine is better than WordPress.

I decided to investigate BlogEngine more. It is a full-featured blog platform with similar functionality as WordPress (but probably not as flexible). As far as they relate to content organization, the blog features that help you organize and navigate your content are as follows:

  • Categories
  • Tags
  • Related Posts
  • Menu navigation

With the menu navigation, if you integrate jQuery, you can achieve the same effects as an expandable/collapsible table of contents in a help authoring tool. For a few jQuery TOC like navigation features, see the first few examples at 50 Amazing jQuery Examples from

Apart from the TOC, the main way to organize content on blogs is through categories and tags. Instead of putting content into folders, you arrange it into categories. When the user clicks the category, the latest posts within that category appear, and the user can navigate to older posts through links at the bottom.

Tags are more granular than categories. Tags function more like index keywords that you use to describe the content. Whereas a post usually belongs to just one category, you might use a dozen tags within that post.

The best example of a software application that uses blogging software (in this case, Movable Type) as a help platform is Jing Project.

Jing's help is on Movable Type (a blog platform)

Jing’s help is on Movable Type (a blog platform)

When you click a category in the help, such as Get Started (scroll to the footer to see this), all other topics within that category (or at least the last 10) appear in reverse chronological order.

Tags function the same way. When you click a tag, all other topics with that same tag appear in reverse chronological order. (Jing Project’s help doesn’t use tags, but they easily could.)

Organizing content via categories and tags gives you a lot of freedom and flexibility, because you can group content quickly and easily. The problem is that categories and tags lose the hierarchy that is necessary to logically arrange the content within the category. The posts within the category or tag are ordered in a flat way (chronologically or alphabetically). This flat organizational model doesn’t let the user know which topics are most important.

You could manually change the publish dates to better control the sort order, but the effect is still a flat list of posts, with no parent-child relationships or folder groupings. Because of this flat list of topics, categories would need to be limited in scope, with no more than 20 topics per category and preferably only 10.

A lot has been written about categories versus tags, particularly for the WordPress blog platform. In the next post, I’ll look at these two organization systems (categories and tags) in more depth.

(By the way, how are you liking these footnotes?)

Update: Due to the negative feedback about the footnotes in this post, I decided to take them out and use more conventional hyperlinks instead.

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.

  • Larry Kunz

    > how are you liking these footnotes?

    I’m not, thanks for asking. From an aesthetic point of view, I find them far more distracting than hypertext links. But I suspect that’s just my personal taste. From a practical point of view, why make me click twice (first to get to the bottom of this page, then again to follow the link) when I used to click just once?

    Anent this post: I like where you’re taking us. Looking forward to number 17.

  • Kristi

    I like where you’re taking us, too, but I am concerned about that flat structure you mention. I find the hierarchy not only useful for indicating how topics are related and their relative importance, but it also helps me keep those things straight when I’m writing.

    Tagging and categorizing are such intuitive tasks to complete when I’m writing a blog post–I would love to have that ease when I’m writing a help topic. Perhaps having subcategories would be sufficient structure to establish relationships.

    I could see writing this way, with a standard, though evolving, set of available tags and categories to keep things consistent.

    I’m not digging the footnotes, either. I’m interested in trying it out for at least a while, though. It’s a web habit of mine to click and explore as a I read. Often I open the links in new windows and look at them later. The footnote still stops my eye, and then I want to scroll to it. I didn’t scroll, though, because I read about what you are trying to achieve.

    In Don’t Make Me Think, Steve Krug talks about following established web conventions, and that if you don’t, the benefits of the deviation should outweigh the cognitive dissonance it produces. I wonder which will win in the case of links vs. footnotes.

  • trainey

    Not a huge fan of the footnotes either – I actually think they’re more distracting than the links. We’ve gotten used to expecting linked text – a footnote adds another second of distraction. Although some data might suggest links are distracting – I personally think most of us have gotten used to them. We click what we want to see more of and use the back button if the original article was compelling enough to call us back.
    The footnotes almost seem counter-intuitive/counter-productive when on a web platform (versus print). Print has no other alternative…

  • Jay Maechtlen

    Hi, Tom
    The hyperlink at footnote #1 is broken, or someone changed the rules? doesn’t work does.


  • Debbie

    i don’t like the footnotes either, they are pretty distracting.
    Why not just give the links at the end of the article. If you’re interested in reading the info you will click them there.

    On a practicle note; i read these posts via an RSS feed in Outlook. When you click the little footnotes you are directed to the top of the page, not to the bottom where the actual links are posted.

  • Daniel

    A blogging platform seems like a good option, the difficult part is to sell the idea to the PM. Yours insights may help a lot.
    By the way, the address of the first footnote lacks some www.

  • Robert Nagle

    Funny, I just wrote a few paragraphs on footnotes and web pages a day or so ago:

    Footnotes have fallen out of favor on the Internet, but they still have an important role to play. If you have checked Wikipedia recently, you will know the reason. Many external links which were added are now dead. Sometimes, valuable information is available online in an offline source like a book or print newspaper. Wikipedia made a decision a few years ago to require that the main text body of their articles link to footnotes at the bottom. The footnotes themselves would contain the hyperlinks to the third party sources.

    That is generally a good practice. First, it allows the page citing the source to include bibliographic information in an unobtrusive manner on the bottom of the page. Second, it gives the reader more clues for finding the original source if the third party source has gone offline or if the URL has changed. Sometimes, when the URL has changed on a third party link, if you know the title or some identifying keywords, it can be relatively easy to find the new line if it is still online. Sometimes it is just helpful to keep information about the source on the same page for the reader’s convenience.

    While HTML has made it easy to create links to external sources, making footnotes is clumsy and time-consuming (even for people relatively comfortable with HTML). Perhaps the concept of the footnote does not translate well to the browser page; nonetheless,a CMS that automates the use of anchors can simplify the process somewhat of creating and maintaining footnotes.

  • KellyK

    I like the idea of using tags to organize help content.

    As far as hierarchy, I agree that that’s important. What about creating a Table of Contents page that lists all the important categories in an outline format, so you can easily see what falls under what? It doesn’t put the posts themselves in order, but at least gives some framework for organizing info. You could also mess with the ordering to put a particular post for each category (the basics of that category perhaps) at the top.

  • Justin Brock

    I love WordPress, too, and the custom menus component of their newest 3.0 release makes creating hierarchies pretty easy, even with the date-oriented publication.

    The real problem with using any blogging platform for technical documentation is that of re-use, even if you categorize and tag your posts and pages. I think you may be able to overcome this, however, by trying the following:

    First, consider all posts topics. Posts are your reusable chunks that can appear in any context. Tag them with all the relevant tags, but only give them one category. Tags should be granular [Installing, administration, etc.], and categories, broad [Product A, Feature X].

    Second, think of pages – or a set of subpages – as your publication targets. On each page, then, you could include titles and excerpts from the appropriate posts/topics.

    Page 1, which is an overview, includes:
    topic 1.1
    topic 2.1
    topic 3.1

    Page 2, which is the complete guide, includes:
    topic 1.1
    topic 1.2
    topic 1.3
    topic 2.1
    topic 2.2
    topic 3.1
    topic 3.2
    topic 3.3

    You could probably also do the same thing with the custom menus in WordPress 3.0.

    Just a brainstorm really, but the point is that you probably could create indexes of structured TOCs this way if you think of posts as the reusable topic chunks of your project.

  • Pingback: July Technical Linkdump | Idiotprogrammer()