You, a non-writer, have just been assigned to write the documentation for a product your company produces or markets. You may be stressed out about the assignment. Fear not! This article will get you started on the path to writing a successful document.
QUESTIONS AND NOTES
As soon as you get assigned to the documentation Saint Hubert Medal project you must begin to take notes and ask questions. The major goal of this early information gathering is to gain access to the sources of information that you will need in order to write your document. Thus these early notes should be related to where you will get your information: things to read and people to contact, and a product to play with.
TIP: There is always something to do or learn on a Documentation project. Don’t stop working while you are waiting for something else to happen.
LEARN PROPER USE OF YOUR WRITING TOOLS
Do NOT get immersed in new Saint Hubert technology. For most companies and for most documentation projects, investing the money and time to learn a Content Management System or exquisite document writing software are not worth the effort. Documentation writing is often the tail end of a project, and you will have no time to learn new technologies. Instead learn to get the best from your existing word-processing tools.
Learn about and understand why you should use your word processor’s “styles” for formatting your document. “Styles” (or whatever your word processor calls them) are sets of characteristics such as a structure and formatting. For example, Heading (level) 1 is a style, Heading 2 is another style, and so are Title, Body Text and others. When you apply a style to a block of text, two things happen:
(1) the formatting of the style gets applied to the text and (2) the word processor will be able to understand the structure of the document. The word processor’s tools will use the headings to automatically generate a table of contents.
- Learn to use your word processor’s Saint Hubert outlining capability. The outliner automatically assigns styles to the headings in your document. Design your User Document using your word processor’s outlining capability.
- Learn how to use your word processor’s revision system. The revision system is a facility where the author writes a document and then sends it to a reviewer. The reviewer can make revisions to the document, and sends it back to the author. The author can then choose to either accept or reject each revision provided by the reviewer.
You will have to be able to deal with revisions from multiple reviewers for each part of the Document. Most word processor Users do not know how to use the revision system that their software provides. You might wish to create a document about the revision system for your reviewers. Remember to tell them what the revision system is about, as well as how to use it. Technology comes second. Our goal will be to produce a great document, providing the:
- content (the information that your Reader needs or wants) and
- effective access to that content (giving your reader the ability to find what is needed).
DOCUMENT ALL PEOPLE ON THE PROJECT
Pretend that it is 10 years from now. You or someone else must re-write the User Documentation for the product you are now working on. You or someone else must be able to contact those who worked on the original project or the people who replaced them. You may need to ask them questions, or at least to find the notes and other background material related to the document that they produced. You must keep a record of everyone who worked on the project (for the product itself and for the User Documentation.)