Some of the processes you find in web applications are fairly standard. Most folks can fill out a contact form, or fill out a survey, or make a calendar entry without the need for too much explanation. But what do you do when the form involves business rules that the user may or may not know, or presents the user with a number of options?
I always try to make sure the tools and the pages I put in my web applications are fairly self-explanatory, especially those tools and pages that only the administrative users of the application interact with.
The folks who end up using and administering my applications (my clients) are almost never technical people, so I start off each administrative page with a brief explanation of what the page does and how you save any information entered on the page. Once they've used the page, they can always skip over the intro and go right into the form or tool.
If the overall form requires a bit of explanation, something that can fit into a few short sentences, I'll put that explanation right after the basic description. If certain form fields require special instructions (like the requirements for choosing a sufficiently-strong password), I'll put the instructions right next to or under the input field, so that they focus on the instructions right when they need them.
Sometimes, though, there's too much to explain and still fit on the page without using up a lot of screen real-estate. In those cases, I'll present the explanation via a JavaScript pop-up window that comes up when the user clicks on a help symbol like a question mark icon.
I try not to use too many of the help icons on a single page, but it's a great way to present additional information to only those folks that need help, without getting in the way of experienced users.
Up until now, those techniques were sufficient to provide my clients with the guidance they needed to use their new application. But my latest project has taken help documentation one step further.
This project allows my clients to create news articles for the web using a JavaScript WYSIWYG editor, so in the prototype I added a few help icons to the editing page in order to explain how to use the editor, how to upload images files, etc. When I showed my clients the editing page and the help icons, I told them I would give them the ability to edit the help text that was displayed in the pop-up windows (so they could phrase the help in a way that made the most sense to them).
They liked that idea, but they had an even better one: they wanted to write their own in-application user manual, so that the primary users of the application could write procedural instructions (instructions not necessarily pertaining to the use of the application) that would guide other users in the office whenever they needed to fill in for the primary users.
So I built a tool to let them write chapters for their manual: they have a simple text field for entering a chapter title and a WYSIWYG editor box for entering the chapter content. They can also rearrange the order of the chapters on the master page using a variation of my jQuery-powered list rearrangement tool (see related entry). The header of the application hosts the "uber" help icon they click to bring up their manual in a large pop-up window, where the chapters are listed as hyperlinks that load the corresponding chapter content into the right-hand content area via an AJAX call.
Only time will tell if they actually write their own manual, but if they do, I may include a manual-writing tool in future applications. If your clients are willing to write some of the documentation for an application, it's a good way to get them further invested in the project, and it can end up saving you some work in the process.
