Help for web applications (part 1: general)

Tweet

INTRODUCTION
When was the last time you thought it was necessary to create an help button for your web application?
I do it everytime that I publish a beta release. I've always thought and I strongly believe that a good web app needs a good online help. It doesn't matter which type you use (an html online help, or a chm, txt, pdf file) as long as you make it available somewhere in your application. I strongly believe in that for different reasons.

WHY?
Basically when I prepare a good meal, I like to present it in the best way I can; so I put the food on a large dish, and I try to make it as much attractive as I can. A good web application needs an help file because it is the inevitable last piece of the whole work. The final user or the people who paid for it will be pleased and satisfied, and your web application will be perceived as more professional. And that is the first reason.

Secondly, you need to let the user being independent, make him aware of things working behind the application, how decisions taken have impacts on the web application itself. The help file might contain useful tips on how to properly use the tool and broaden the knowledge on the basic and advanced functionalities of the web application.

Third: provided that the user read the help file, it might even give new evelopments and improvements based on users suggestions. In my experience the feedback from the user must not be overlooked. Never. And the online help could be used to "force" some sort of feedback.

Fourth: you do not really want to instruct every user, preparing lessons, creating powerpoint presentation, and explaining everything in neverending meetings. A do-it-yourself teaching lesson is much (much!) more suitable and cost-effective than anything else. You can always get back to users when they give you a list of troubles and questions. Believe me, those meetings will be shorter and more effective than expected.

Fifth: you could use the help file as some sort of reminder, a broader list of comments (broader than the one you usually put in the code itself). If you use a word processor to create it, you could add notes, revisions and comments everywhere; you could hide them or share them with users. Either way you will help yourself a lot in the application development process.

THE CONTENT
Talking about the content, I usually start with a general description of what the application is doing, what it is used for, and what are the expected results. A general knowledge could be used to instruct users on the purpose of the web application and, basically, to answer the question "Why was it developed?". Usually I get on in answering all the other questions - like "How was it developed?" and, if I need to go deeper and I feel it is necessary to give those information,  "When and where was it developed?". It is up to you to decide whether to write those things or not.

After the introduction, you need to explain in depth all the menus and what they are used for. I usually start from the main menu and then jump to submenus, basically following the structure of the application itself. That is my way, you can choose your own as long as it has a logical flow. This is quite important: the single chapters in the help file should be independent and part of whole at the same time; that will help people in the reading process, and again it will provide a good source of information on single issues.
Sometimes at the end of a chapter I write down a "tips and tricks" section as you might have seen in dozens of programming books, just in order to give extensive and additional guide lines.
While I build the help file, I check on the document index and that every chapter is in the correct place, searchable and clickable.

In the writing process, I try to leave technicalities out, I try to get to the basic of it, imagining to talk to my 7 year old son. It is very important in my opinion that all aspects of a functionality is deeply explained, but remember that you are not writing for a programmer. The final user - as you may already know - is a strange individual, and I found that the most difficult part is to get into his point of view, just to write down instructions consistent with the user's needs.

Another thing to keep in mind is that you will need to update the help everytime you improve or change your application. So I usually try not to put elements that need to be updated and that don't really enrich the helping process. I am talking about images of the user interface for instance: if you change the css files, the main menu position or any visual element, you will need to recapture all the images and that might be time consuming without a real advantage. However sometimes you really need to put those images, but in that case, use them with caution, put just a few and only if strictly necessary.
 
At the end of the work, you might add a glossary, add images (even if I do not like it as explained), charts or whatever you feel is needed to better explain the application.

As you may have noticed, I usually prepare my help file using a word processor, just as a start. I might end up preparing a pdf file, or a series of html files, it doesn't really matter. I like to create a first draft that way. Then I will create the final online help the way I feel is better for users and the web application itself.

The second part will deal with the actual creation of the help file.