During my career I’ve written everything from press releases to planetarium shows. For the last 15 years, however, I have been writing Help files for software programs.
Samples of my technical writing are available upon request.
Ten Tips for Writing Help Carolyn’s Way
- Write simply.
People reading Help want to get things done; they don’t have time to admire your extensive vocabulary and sterling prose.
- Be brief, but be thorough.
You can only break down complex concepts so far before you lose meaning.
- Be direct.
“Never delete X” is better than “You shouldn’t delete X.”
- Tell readers why they should or should not do something.
“Never delete X because the program needs X to run correctly” is far better than “Never delete X.”
- If it’s a feature in your product, the Help should mention it.
Maybe one person in a hundred will need that information, but when they need it, they need it.
- Make it easy for users to find what they need.
Think in terms of search engine optimization and include not just the application label but the words readers might use. For example, your function may be labeled “Schedule,” but if the reader thinks of it as “Calendar,” you should include both words in your topic and index.
- Each topic should include all the data on that topic.
If this rule makes the topic too long, break the topic into shorter chunks and clearly link the topics to each other.
- Write for experienced users and new users.
The first group just need reminders, while the second may need concepts explained and examples to show how and why. If your Help Authoring Tool allows for it, hide these items under a link such as “More Information,” “Examples,” or “Tips for New Users.”
- Use all available tools to perfect your writing.
For example, in addition to spell-checking and grammar-checking, test your text with the Microsoft Word readability function. If the text scores higher than a ninth grade reading level, re-write it. Your readers are highly intelligent, but they’re also very busy. The easier your Help is to understand, the faster your readers can solve their problems.
- Follow the standards or style guide used by your client or employer, and follow it to the letter.
We all have our preferences (such as whether we like the Oxford comma), but when you’re writing Help, you’re representing the person who is paying you, and their preferred style outranks yours.