Does online help need an overall structure?

The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it? This is a period of talking to the product managers and subject matter experts and reading up on everything you can find that sheds light on the world in which the product will live.

Next, after you've got a decent understanding of the subject matter, you then start looking at the application (what there is of it so far, plus any plans/designs/user stories you can find for what will be appearing in future iterations of work) and you talk to the project managers, developers and testers, and hopefully you also get to talk to some beta users or user advocates.

Then you can begin to plan your help system. What's the top-level structure going to look like? How are you going to break it down into sections and subsections. Several years ago I worked on a help system where we spent weeks drawing up a complete TOC for the help, and getting it reviewed and signed off, before we started writing a single topic. Needless to say, that was long before I'd heard of the Agile development approach.

But my previous couple of posts have got me thinking. If we could do away with the TOC maybe we could do away with any structure outside of individual topics. And if we could do that then we could cut out a lot of the preliminary process outlined above. It might mean we could get to the point of creating useful content much more quickly.

The ScreenSteps approach is worth considering here. It goes something like this:

• At initial release, the help system just contains 10-20 questions that you know users are likely to have
• After release of the software, the help system grows over time as users ask questions and you add the answers to those questions to the help. But note: you only add new content in response to real questions
• New help topics get dropped into the help as you write them. Users can find them in a search and you can send them a link that'll get them straight to that topic. Consumers of the help don't need a TOC.

The ScreenSteps Documentation home page is a great example of a simple documentation interface:

Notice how predominant the search box is. You could claim this page has a table of contents - it kind of does - but it's not like the traditional, elaborate expanding-tree TOCs you find in many online help systems. It's just a simple series of links. If you click one of these links you get to a similar page with more links, from which you go to an actual topic. So there's never more than one hierarchical level of links on screen at once, and you're never more than two clicks from a help topic.

And what I really like is that this allows you to keep adding topics without always having to decide where to place a link in a tree TOC. Just write the topic and get it in there for users to see. If it merits a link in one of the secondary links pages you can go and add one, but I'm pretty sure most people using this system will get to content via a search.

I'm convinced these days the majority of us are searchers rather than looker-uppers. So the search box serves the majority searcher community, and the links are there:

1. For the minority looker-uppers
2. To direct people quickly to popular topics. Hopefully you're able to use the logs from your web server to spot the topics that most people go to and you can design appropriate first and second-level links to get people there fast.

Maybe it's time to retire the old tri-pane online help:

Apologies to ESRI. I'm really not slagging their online help (acually I think it's very good). It's just the first internet-visible tri-pane WebHelp I could think of.