ITauthor

I've written before (see Does online help need an overall structure? and What online help needs is really good search results) that I think the best way to present online help is with a simple page with a big search box at the top, above a selection of links likely to be useful to users needing help. Do away with the book metaphor used in many help systems: the table of contents and the index. Just make sure the search gives really spot-on results.

So I happened to be resurrecting an old Yahoo email account this evening and I couldn't resist clicking the Help link to see how Yahoo do their online help. And, lo and behold: a big search box at the top with a well-chosen selection of links below.

It's an email system, so I tried searching for "spam" and I got a very decent set of results:

And clicking on a link took me to a nicely pitched little tutorial topic on avoiding spam:

So the result is that from the help page I just have to do a search and click a link to get straight to some useful help. That's how it should be to get help with something on a computer. Anything more complicated than that has a problem. 

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.

Tom Johnson recently wrote a really though-provoking post about the scope of help content. What you’re reading here is based on a comment I added to Tom’s post.

Tom describes helping out with user support for an application. He also works on the online help for this application. He describes how useful this contact with users can be. He writes:

I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

Talking to users. Wow! That's how it should work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. Our end users (yes, I know, horrible expression, but what I mean is not the administrative users, or the managers, or the customer’s support staff, and not the decision makers who you sold the system to originally but who will never actually use it, but the people who have to use the software day-in, day-out as part of their jobs) … hang on, let me start that sentence again. Our end users contact their internal support staff and, if they can't help, those support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we're in a different part of the building). So it's not unusual for tech writers to work on a product for months, or years, and never talk to an end user. Their knowledge of the end user tends to come second hand, through the product manager or some other SME. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

So Tom’s post got me thinking: maybe working periodically in support is something all tech writers should do.

Tom’s post also referred to an old ITauthor podcast where Graham and I discussed how much you should document. I must admit I’d completely forgotten about that one. I should probably listen to it again some time.

But what I think I probably said in that podcast, and it’s what I really believe, is that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I've seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It's the scatter-gun approach: "How should I know what users will want to know about? So I'm just going to document as much as possible."

I'm convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don't need help with that. It tends to be the secondary things - the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious - it's those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

Tom’s post and the comments after it talk about how, as a result of users asking questions, and perhaps contributing answers to user forums, a help system can continue to grow and improve. And it’s obviously a good idea: after the initial, good-enough-for-release version of the help, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

Tom, who I’m assuming works on hosted WebHelp, describes how whenever he gets a support question that is now answered in the help, he goes and writes a topic answering the question, rebuilds the help and then replies to the user with a reference to the new topic. I think this is a great idea, but it only works where you host the WebHelp. If your customers host the help on their own server, or if the online help is traditional client-side CHM files, then it can be months before users see the next version of the help system.

One of the comments I really liked was by Larry Kunz. He writes:

As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums - either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

Is this yet another alternative title for our role: information curator?

After commenting on the post I continued to mull it over, in particular the issue of finding information in a help system that just keeps growing and growing. Tom writes:

in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics

This gave me a radical thought. Isn’t it about time to do away with the TOC and the index in online help systems? Both the table of contents and the index features of printed books that were pulled across into online help, way before Google appeared in our lives, and maybe they’re just not appropriate for online help.

Surely what we need is really good search results. How do 99.9999…% of people find information online? Through a search engine. The more I think about it the more convinced I am that, if your online help had a great search engine, you wouldn’t need to worry about the system growing and growing as questions and feedback from users helped you add the information they wanted to find. Better still would be the situation where a user community forum helped you build into the help the answers to questions people had actually asked, rather than the tech writer’s best guess of what they might ask.

So come on help tool vendors, give us really good search results. The search functionality in Madcap Flare’s WebHelp leaves a lot to be desired - try doing quoted searches. If you publish WebHelp that’s publicly visible, you can use Google as your search engine and, while far from perfect, that’s probably going to give you the best available search results right now. But what if your WebHelp is hosted on an isolated corporate network? Or what if you’re tied to delivering old-style CHM help for the foreseeable future? Back to the help tool vendors in that case. Come on: give us really good search results.

From making a habit of talking to non-technical people about how they figure out how to use software, I’m convinced the majority of people wouldn’t bat an eyelid if the TOC and index disappeared from help system and the landing page for help was just a simple, Google-like page with a box to type in your question and a big old Search button.

I was at a meeting in Ayr on Thursday. When it finished I just wanted to get home as quickly as possible (Ayr to Edinburgh is about 83 miles).

Naturally, as is my habit, I took the first available wrong turn and very soon found myself driving around an unfamiliar Scottish seaside town in the rain.

This is why I need sat nav. And it struck me, as I was stuck at yet another set of traffic lights, that context-sensitive online help in a software application is like sat nav in a car.

You never notice how badly signposted towns are until you're lost. Then it becomes painfully obvious just how often streets don't have a street sign on them, and how road signs tell you your destination is in one direction at one junction but when you come to the next junction the destination isn't mentioned and you're left to make your best guess. Signs are often only designed for locals - so they indicate how to get to places a few miles away, but they're no use if you want to get out of town and go somewhere else.

This is like software. Poorly designed software is difficult to navigate and often only takes into account the most likely use cases. If you're doing anything even slightly out of the usual, then you're own your own mate!

Without sat nav, when you get lost, you can generally do one of two things:

1. Ask an expert
   This involves stopping the car and either asking a local, or (usually more reliable) phoning your nearest and dearest and asking him/her to look up Google Maps and work out directions for you.
2. Look up a map
   Again you've got to stop the car. You've also got to keep a road atlas in the car. And you've got to rely on it being up to date.

The software equivalent of 1, without online help in an application, is asking a colleague to help you out. This takes you away from your computer, interrupts someone else's work and requires a patient local expert. There's only so many times you can use this workaround before it gets very irritating for everybody.

The software equivalent of 2 is reading the printed manual. This assumes there is one and it's up to date. Again it disrupts the flow of your work within the application (like stopping the car to dig out the map).

Other similarities between context-sensitive help and sat nav are:

• It should be available when you want it.
• It's got to give you correct information.
• It should tell you only what you need to know.
  Verbose online help is about as irritating as a sat nav that keeps telling you to "continue straight on" rather than shutting up until it's time to turn.

Anyway, to finish, here's a Sunday-best picture of Ayr (it wasn't looking like this on Thursday).

Don’t you just hate it when software tries to be helpful but just gets in the way?

I’m currently working on tidying up a migration of RoboHelp into Flare. I’ve got to say immediately that Flare does an excellent job of migrating RoboHelp projects – but only if you’ve only used RoboHelp from within it’s GUI and never gone and tinkered with the HTML or added your own Javascript.

Huh! What are the chances of that?

Any help project from a few years ago that was built in RoboHelp will definitely and certainly have some tweaking and augmenting to it – or it will look like rubbish and be clunky and unsophisticated. Things might be different in the current version of RoboHelp, I don’t know, I don’t have it – but previous versions of RoboHelp had some serious shortcomings that forced you into a bit of roll-your-own behaviour just in order to get things looking and working the way you wanted.

The trouble is, once you do a migration into Flare, none of this is handled for you. I’m not complaining about that. The guys at Madcap have no way of knowing what extra goodness you layered on top of your plain old RoboHelp projects. And fortunately, most of the time, Flare just leaves any stuff you added by hand. That way you can do what I’ve been doing over the past few days: you can run some crafty regex search/replaces to go and convert those things into something that’ll work in Flare.

Unfortunately though, the philosophy of “if you don’t understand it, don’t touch it” hasn’t been extended to the TOC processing. The TOCs in the projects I’ve been migrating use anchor names at the end of topic file names, to pass a value to a redirect file, which then sends the browser off to display the appropriate page. Why would you want to do that then, I hear you ask. Well it’s a nice little Rob Chandler trick that allows you to decide which entry in the TOC gets highlighted where there are multiple TOC refs to the same topic. If you don’t use this method, the TOC will always jump to the first reference to the topic.

After some laborious debugging I’ve discovered that, at build time, Flare is taking my TOC file, seeing references such as redirect.file#sometopic and stripping off the anchor. So, within the generated .chm the reference is just redirect.file, which results in no redirection happening because the Javascript never finds out where to redirect to.

Flare does the same with query strings, like redirect.file?param=value. Annoying! Very annoying! It’s like when you were a kid and your mother tidied up your bedroom and chucked out your favourite comic. “Well it was lying on the floor. How was I to know it was important?”