Fog Creek Software
Discussion Board

Writing Help files

I was just given the exciting task of writing a help file for our product.  Now, I don't need to know how to use help applications, I'm just writing in MS Word for now.

The question I have is, how do I write a help for an application?  Listing each button or form field and what it's for doesn't seem helpful to me.

It's not a tutorial, so I don't take the users through step by step.  I'm an IA, and do UI work, writing is not my forte, but since I've been charged with the task, I'd like to make the best of it.

Tuesday, March 16, 2004

There are people who do this for a living -- they hang out on -- and they'll probably have better advice that I do.

My opinion is that there are three useful things to put in a help file or documentation.

(1) a tutorial - something that takes 10 minutes to an hour and walks a new user through the major areas of functionality, so they can learn the basic concepts
(2) reference material - ad hoc detailed reference material linked from the UI using "help" buttons
(3) domain documentation - enough to teach people who are new to the domain what the product is trying to do. For example Quickbooks contains an excellent manual that tries to teach basic small-business bookkeeping principles, because they know that a large portion of their audience has never done it before and just explaining "how to create an account" isn't good enough for people who don't understand the concept of an account in double-entry bookkeeping.

Joel Spolsky
Fog Creek Software
Tuesday, March 16, 2004

I can't recall right now where I found it, but when I have to create help for my applications I always break it down into this outline:

1. Quick reference. These pages contain brief lists of steps to perform the most important program tasks. If your user only uses the software occasionally, he/she can access these little "how-to" lists to get going. Don't include in-depth explanations of all the options here.

2. UI reference. One page per application form (or maybe a few for tabbed forms or equivalents, if they're pretty involved). Includes a big screenshot and a list of what all the buttons do, with links to more detailed topics.

3. Background. In-depth information on the main functions of the program.

4. Reference. This may include information for sys admins, file formats, and other tech weenie stuff.

I like this outline, because I find most users fall into one of two groups: the ones that rarely use the program and need the step-by-step guides, and the ones that use the program all the time and need reference information handy.

Hope this helps.

Bob Kingan
Tuesday, March 16, 2004

If writing Help is anything like writing manuals, you might want to make it "task-oriented": consider that users don't really want to learn the program, what they do want to do is perform some task.

If I were writing a manual for Outlook, for example, I might have a "task" like "How to send an email". Note that sending an email involves many different screens and buttons (the "Create Mail" button on the main toolbar ... the "Select Recipients" dialog from the "To" button on the "New Message" dialog, etc.). They might like to see "How to send an email" as a task-oriented topic, which guides them through the screens, in the sequence they need for that task. This might be better than a "reference" manual which describes items in a sort order determined by the program (e.g. "all buttons on the main toolbar") instead of in a sort order determined by the task.

There may be more than one way to perform a task (e.g. do you create a new contact while you're creating the email, or before). This kind of "several ways to do something", like 'decision points' in a flow diagram, may be implemented as hypertext links to other sections in the Help.

Christopher Wells
Tuesday, March 16, 2004

The first thing I would do when writing a help file is to look at the application and EVERYTIME IT ASKS YOU A QUESTION write some help text to explain what the choices are, what the implications are each and why you might want to choose it.


'Do you wish to save before exiting? Yes/No/Cancel'

Yes - the information that you have typed into this purchase order will be saved back to the database ready for use.

No - anything you have typed since you last saved this purchase order will be discarded. You might use this option if you made a major mistake and you want to start again.

Cancel - just closes this message and lets you continue working on the purchase order. Choose this if you clicked 'Exit' by mistake!

If in doubt, choose Yes

Your users will love you even if you do nothing else.

I'd then write help for each of the icons and widgets that have been developed for your application. Be careful to explain any terms or concepts that have been developed for your application that do not map 100% to the users' domain.

THEN I would look at the tasks.

Les C
Tuesday, March 16, 2004

Examine help files that you think are good and emulate those.

I found Microsoft Office 2000 documentation to the best.  Not its implementation (the "Answer Wizard" tab is crap), but its content, links, etc.

Every window should have help for it, including an explanation of each option, check box, etc.  And (this is important) WHY you would want to choose that option.  What are the consequences of one choice versus the other.  Link each window to conceptual and procedural topics.

Examples of poor documentation include anything Adobe.  Adobe Acrobat opens a useless pdf file.  Adobe Photoshop Elements help is useless.

Nero CD writing software doesn't bother to explain anything useful to me.  There are options in dialog boxes  that are never explained anywhere.  There's an option for something called "Jitter correction."  I don't know what that is and why I would want to enable it.

Word Perfect 10.0 does not have an index entry for "versioning".

You refer to writing the help as "exciting."  You could look at this an opportunity to improve your product.  If you find that you can't explain some feature easily or it takes 12 steps to accomplish a task, maybe a look at the interface is in good order.

Get a hold of "Microsoft Manual of Style for Technical Publications."  Google it--it's free.  It's a great place to get started writing clear, concise and intelligible help.

Wednesday, March 17, 2004

I've found Office 2000 Help to be anything but helpful, especially the VBA portions. It's not that the content isn't good; on the contrary, it's the best in the business. But the indexing was somehow screwed up, so the article you need is impossible to find unless you know exactly where to look in the table of contents.

I guess the lesson to be learned is that a help system is only as good as its search mechanism lets it.

Wednesday, March 17, 2004

Martha makes my point.

The Microsoft Office developers wrote excellent documentation, but then modified the interface from a perfectly good thing (HTML Help) and made it unusable.

Around here we use the Access 97 help instead of Office 2000 help.

So I found  the chms that relate to Access and VBA, then  decompiled it and then recompiled it so that it works.

Shame on Microsoft Office.

Wednesday, March 17, 2004

Something that I hope goes without saying - writing good help, like writing good code, is a skill. A good coder is not necessarily a good help writer, and a bad help writer is not necessarily a bad coder. Writing help should be given to someone who is good at it, and preferably wants to do it. I hope that was you.

David Clayworth
Tuesday, March 23, 2004

*  Recent Topics

*  Fog Creek Home