What Content Belongs in Help Documentation
By: Johnathon Wright on: October 17, 2007
It is always tempting to start to create help by opening word and typing, “The employee information screen is used for creating, reading, updating and deleting Employee information. Here is a screen shot, which hopefully looks like the site you're visiting. Otherwise, something has gone wrong.”
Since the entire functionally of this screen is so blatantly obvious to developers, it’s hard to go any other way. Here are a few guidelines for creating more useful documentation:
Recognize and explain the scope of the screen
“The Employee Information screen gives you a single point to manage all the information about an employee.”
Be sure to mention the implications of a screen
“Changing the information here will affect an employees’ information anywhere it appears in the system.”
Provide Examples
“For instance, if you change an employees name on this screen, the new name will appear on all future time sheets, their welcome screen, etc. This change will happen immediately.”
Provide information about permissions / security / auditing
“Users are limited to viewing only employees that are relevant to them. For instance, only the payroll administrators group and Executive Team group can create, read, update and terminate all information about all employees. Department heads can see a limited amount of information about only the employees they manage. There are other rules, and they may be specific to your company.”
Q&A
Once you've covered the basics, it may be awkward to add a whole bunch of small details you think might be helpful into a paragraph format. Just go straight into a Q&A section. This can be taken to the next level by making it dynamic so users can actually post questions.
Still confused?
You aren't going to have all the information they need. Tell your users what to do if they are still confused. This can take the form of further reading links and/or a contact form.
For more information see: * Section Title * Other Pages * Stuff Here
Still confused? Ask your question here. We’ll email you and update this document.
- or -
“See your payroll administrator for more information.”
- or -
“Contact us at (800) HELP-YOU and reference the Employee Information Help Screen”
- or -
“Click Here to email us.”
Visual Aids
A picture can be worth a thousand words. Or none.
Some people love to put screen shots in their help documentation. Just like using Power Point for presentations, this tool must be used carefully. Are you actually adding value but putting a screen shot? A rule of thumb: If you're not having to draw on your screen shot to point something out, it's probably just wasting space. Remember: Your users already have a screen shot. It's called your application.
Having covered the essentials above, write as little else as possible in the "About this page" section. For instance, I am against describing / explaining validations. They should already be self explanatory. Plus, NO ONE is going to remember to change the help when you suddenly aren't requiring the middle initial any more, and suddenly your help is out-of-date.