The Structure & the Content of Help files
For me help files can be divided into three main sections:
ï Introduction, which includes a general presentation of the application, install / uninstall the application and minimal requirements to use it. It may also include any specific set up and configuration guide.
Some of the information should also be available in the printable Start guide and in the printable Installation guide as the help file is usually installed together with the application itself.
ï The How To section(s), which is the core of the help file and should provide the users will necessary information in order to accomplish specific tasks and activities. This is the most importation section.
ï Contacts & Support, which gives the users the necessary information to get in touch with us and take part of information how to get updates etc.
Keep the language simple and straightforward. The UI of the application is what the users usually see and therefore there is no need to add technical details that the users never will take part of, i e avoid information overload.
(No, most users are not interested to learn how amazing UDFs or procedures weíve been creating to solve specific issues withÖ)
If the application explicit target beginners then itís highly recommended to either avoid the use of abbreviations or explain them. The same is valid for all the buzzwords that tend to be in use but never explained (Iím no exceptionÖ).
However, it does not necessarily mean that all the explanations should always be on a basic level. A good judgment should guide us to decide the level of complexity together with information about the target group of the application.
Use screenshots as they give the users a quicker and better understanding where to do the activities in the application.
Avoid using too many hyperlinks and too many popup. If You believe You need many hyperlinks and/or popup then You probably will need to completely re-design the structure.
Check the spelling in the help file. Personally I can get irritated if common words are misspelled and beside that the impression of a professional applications increase if misspelling is avoided.
In my experience itís a good situation, if possible, to let a member of the target group help out with the creation of the help file. An even better case is if a professional documenter does do the work but so far I have not yet have had that possibility. For smaller projects itís not reasonable from a strictly financial point of view.
A helpfile should include the following tabs:
Both the Index- and Seach-tool may seem to be overkilling but some users actually use them instead of drilling down via the Content-tab. Except for that I would say that the existence of the tools reflect the present standard for help files.
The following screenshot shows an example of the basic structure and the content of a help file:
(Yes, the names of the tabs etc in the above image are in Swedish).
It may seem to be a simple task to create help files but in my experience it takes a while and lots of practice before we can create help files of good quality.
The process of creating helpfiles gives us valuable input on how the applicationís UI is structured and it can also help us to detect any major flaws in the UI.
Over the years a practical standard seems to be developed for how help files should be set up but as far as I know little has been written about it. Hopefully some of the above will give You some ideas about it.
In the next post I will discuss how to create help files with a help authoring tool (no, itís not with Excel ;) ).