The most common advice given to people writing help or documentation is, pretend you're computer illiterate. Imagine you don't know anything about computers. This is either harder than it sounds, or people's imaginations aren't what they used to be.
Better advice, I think, would be to ask yourself some basic questions :
1. Where is the option/feature accessed from ?
2 Why would I use it ?
3. What happens when I use this option, and is it different sometimes than others ?
4. Which data/documents/windows are affected ?
5. When can/can't I use this option ?
Let's look at an example. Take the typical File -> Save menu item. Documentation for this often looks like the following;
Save Menu Item
Saves the current changes.
Great. Doesn't tell us anything that 'Save' on the menu didn't already. Does the save option save only the active document, or all documents ? Is it disabled if there haven't been any changes since the last save ? What if the file is read-only, or if it was opened in read-only mode ?
More importantly, let's look at the typical behaviour of the Save menu item. Let's say Bert starts a new document, he types away and then he wants to save his work. He finds the File -> Save option, but he's confused about where it's going to be saved. He wants to save it to a floppy (he's a typical home user and is still running a 286 he bought from Noah, since he doesn't need a PC that works faster than he thinks). He checks the help, which only tells him it saves his changes. Now he's confused. He still doesn't know where his data's going to be saved, and his document is new, so if File -> Save only saves changes is he looking at the wrong option ? How does he save a new document ?
Ok, so he decides to be brave and try the option anyway. Now he gets presented with the typical Save File dialog. Two problems here, one, this likely isn't documented in his application's help since it's considered 'Standard'. If he wants help on how to use this dialog to save to a floppy disk he's going to have to read the Windows documentation, which he probably doesn't realise, probably doesn't have (second hand PC/OS ?) and probably won't do anyway. Plus, he's a user, we're lucky he's reading the documentation for the application in the first place. In fact, we're lucky he can read !
Now, let's say he works out the File -> Save dialog and manages to save his document to a floppy. He closes down his PC and doesn't think about it any more for a week.
Now he's back and he needs to do some more work on his document. Let's just assume he manages to find the document on the floppy and open it (yeah, right). Bert now makes his changes, and he wants to save them butt his time to a new file so he can keep the original. He happily clicks File -> Save knowing the save option presents him with the Save File Dialog - Oh wait ! It doesn't ! Worse yet, he's just over-written and lost the original. There will be tears before bedtime.
Ok, putting aside the possible design issues with the open/save dialogs, the File -> Save option itself, not to mention the whole drive, disk and file system tree which users often don't get, good help could've prevented a lot of frustration here.
Based on our original questions we could write;
Save Menu ItemLocation
This option is located on the File menu, on the menu strip at the top of the main window.
Use this option to save a new document, or changes to an existing document. By saving your changes they can be recalled again later, even if your computer has been turned off in between times.
When this option is selected;
- For new documents the Save File dialog is shown, allowing you to choose where to save your document and what it is called. You can also select various formats to save your document in. For more help, see your Windows manual.
- For existing documents, or documents that have already been saved, the file is saved again using the last location, name and format. There will be a slight pause when the document is saved, and the status bar at the bottom of the screen will show 'Document saved'. If you want to save your file to a new location or a different name/format then choose the Save As option on the File menu.
If an error occurs during the Save operation, a message box will be shown explaining the error to you.
The save function affects only the active window.
Not Allowed When
This option is disabled (shown with grey text and can't be clicked) if there are no changes to save.
This is fairly generic help (for a generic situation), and it isn't perfect. A better idea than directing the user to the Windows documentation would be to document the dialog ourselves, or provide an actual hyperlink to the Windows help page for the specific item we're discussing. Hyperlinks or pop-ups for other items, such as the 'Menu Strip' and 'Active Window' concepts would also be a good idea, as well as a link to a 'concept' page on different 'formats' might also be useful. A picture speaks a thousand words too, so a screen shot showing the Save menu item expanded on the File menu and possible what the 'active window' looks like might also be useful.
That's beside the point however, because the help we have given is useful because in several situations, unlike the original help we had.
First of all, we've told the user where the item is, so if they can't find it at all, the help will direct them there. Of course if there were any circumstances when this item was made invisible or moved to another menu (perhaps on child window) then we should note that here. It's important to remember that users don't always find items in the help based on context, some users actually read from end to end or browse manuals and help files, others may have come here from a link etc.
Next, we've told the user what this function does. With the Save option this should be self-explanatory to even the least computer literate user, but we can't take that for granted. Note that we do mention here that the function can be used on both new and existing documents (changes).
The Usage section is possibly the most important. Here we tell the user exactly what to expect when they click the button, and how to tell if there was a problem or if the function succeeded. We cover the fact that the function does different things the second or subsequent times it's used, or for existing documents rather than new ones.
The Effects section tells the user what the scope of the operation will be. This is important, especially in MDI application where a novice user might expect 'Save' to save all the open documents.
The Not Allowed When section is possibly the second most important section, even if it's the last one. This gives the user the all important information about when/why the option is disabled, and what to do about it. Of course, you could also help them out with this by implementing my Disabled Tooltip Component for .NET.
So we've gone from one not very useful line of text to several paragraphs of information that are all useful at different times - and all this for a relatively standard function that's available but poorly documented in most software !
That brings me to my next point - standard functions. It's generally not good enough to say "I don't need to document this, it's a standard so everybody knows it". Apart from the 1% of users who might be using your application as their first/second/third even program and might not have figured out or had the standards explained to them, there's a problem in that unless 100% of software acts exactly the same way then some users are still going to be kept up at night wondering if they really should click that button or if your program is one of those weird ones that works differently.
Maybe you've tried to simplify your program by removing the Save As function and always showing the file save dialog. Maybe you've built your own dialog to remove unnecessary complexity in the existing one. Possibly 'Save' doesn't make sense in the context of your application, or it automatically saves changes after each one is made. All of these situations need to be documented, as does the 'standard', if that's how your application works - because someone else's program might be different and that might be what your user is used to.
The second part of this rant is about help systems themselves. It seems to me the help systems we have today are pretty terrible. Of course better natural language queries would help, although the Microsoft Office help systems do an ok job of this most of the time. The problem goes deeper than that though.
First of all, most help systems are extremely slow to load compared with applications, and the bigger the help the worse it gets. Ever hit F1 by accident in Office, SQL Server, Visual Basic or Visual Studio .NET ? There's usually enough time to make get your cake and eat it too.
I also think it sucks that most helps systems are 'compiled', and included in the compilation is the display format as well as the help data. If you go looking for systems to generate help for .NET assemblies from the .XML documentation files the compiler can create you'll find lots of them that use plug-ins or style sheets to achieve different looks and feels. That same applies to 'user help' creators. Why ? Why isn't the help content stored in a database, or better yet some open standard like XML, and then read directly by the help system with whatever 'style' the user has chosen as their preference being applied when the data is displayed ?
Also, since most help doesn't make sense to users, why can't they update it themselves once they've worked out what's going on ? I guess this should be sort of like a Wiki, but there needs to be two or three levels of 'edit'.
There needs to a 'local' edit which can be made just on the users PC or for users on that local LAN. This would allow them to make general internal comments just for themselves, either that make sense to them (without having to be in pristine English) or with their own internal company policy notes about usage.
The second level could possibly be a more 'global' edit where the change is posted to the web and available for all users to see. This is more like the Wiki concept.
The third style of edit would actually be a support incident. Like Microsoft's knowledge base or help that says, "Did this page help your solve your problem ?", but instead of just taking a boolean response it should allow the user to key in their problem/question and have it posted to a support desk. The support person receiving the problem can then post a response which can be sent back to the original user, and optionally (based on the support agents choice) posted as an addition to the help on-line.
The key factor here though is that help, both the original and the changes, must posted back to the user's PC. I am always frustrated by software that only has 'on-line' help, whether this is just pages on their site or something fancier. Sometimes people use software on laptops (or even desktops) without Internet connections, some people are still using dial-up and don't want to have to wait for a connection (or pay their ISP for the time/traffic spent getting help for your application).
What if your application only runs when there is an Internet connection available ? Well you'd still better make your help file available off-line and outside of your application. Bert may be telling his friend Earnie about how great it is and then Ernie asks if it supports feature X. If Bert doesn't know but he has his laptop then he's likley going to try checking the help to find out. It's not going to be a good look from either Bert or Ernie's perspective if he can't even find out the answer to that simple question because he's not connected right now.
Personally, I'd also like better interconnection between help files. I really don't want to have to document the open and save dialogs in every application I write, even if I can write the documentation once and 'link' the source files into seperate help projects. I need a good, simple way of linking to the existing Microsoft help, or a common help file of my own. I also need the link to be super fast when the user clicks it, I don't want them waiting for the entirety of the help for setting up active directory and burning CD's to load when all they want to know how to do is browse for drives in the Save dialog.
Finally, all help systems should have a 'favourites' option (which Microsoft have been pretty good about implementing recently). If only I had a penny for every time my father said, "I know I did this last week, I just can't remember exactly how..." !
So, how good's your documentation ?
Have you got any ideas about help systems ? Disagree with me ? Why not leave your comments here...