- Keep it concise
- Keep it accurate
- Make it complete
Software engineers work under very stressful deadlines. When they need information they need it now. They want to go in, find the answer they seek, and return to whatever they were doing before. Preferably as quickly as possible so they can move on to the next feature they need to code. Therefore, it behooves the writers of technical docs, especially those that address software engineers, to follow a few simple rules to make the information available in a manner that helps the software engineer get on with the job at hand.
Keep the information concise. I do this by layering the information as much as possible. Will the tool tip answer their question? If not, does the cheat sheet provide enough of a clue to jog the engineer's memory so they can continue? Does the link in the cheat sheet take them directly to a page that will answer their question completely. Or better yet, use command-links to take them to the window, view, or wizard that solves their problem?
Keep the information accurate. Nothing worse than having inaccurate documentation, forcing the reader to dig for the info they seek, or worse yet, weigh two or more different pieces of information to determine which one is correct. Verify component names, use the correct terminology, provide copious links to other parts of the manual to answer other questions that may arise during their search.
Make it complete by answering the most common use cases up front. Once those are answered, look at any special cases that can arise and answer those as well.
Solving a user's problem in documentation should be like peeling an onion. Every layer they peel off should reveal more information that helps answer their question. The sooner they get their answer, the sooner they can go back to what they are supposed to be doing, and the happier they will be with your product.
And we all want our customers to be happy, right?
No comments:
Post a Comment