The technical writing process consists of four phases:
The phases of the technical writing process
are not necessarily discrete. You might start the writing phase before you complete the planning stage, for example, or you might have to deliver the documentation before you feel it is finished. It is highly unlikely, however, that you will ever archive the documentation before you deliver it!
Some products are released several times. In this situation, you might be in the delivery phase of the first iteration of the project while you are in the planning phase of the second iteration. Don't panic: overlap in the technical writing process is quite normal.
Every project is different. The process described here might not exactly describe your situation, but it will be pretty close.
Determine which documents and other information you will create:
system administration guides
routine maintenance procedures
command reference guides
Note: Ensure that you know the terms of any contracts between you and your client or employer, or between your client/employer and their client. If a document is not specified in the contract, do not write it without first talking to your supervisor. [My thanks to Judith in Australia for telling me about a company that didn't check the contract.]
If the documentation is to include tooltips, error messages, notifications, and dialog boxes, develop a plan to ensure that the wording of these is consistent, clear, and grammatical. Since the design team rather than the documentation team often writes the error messages and tooltips, etc., contact the system architect to work out the details of your plan.
I once worked at a multi-national company where each developer wrote the tooltips and error messages for the small part of the application he or she was working on, with the result that the tooltip for each Name field was innumerable variations of "Enter the customer's name, 5 to 20 characters," and that many error messages were ungrammatical, cryptic, different when they should have been identical, or just plain amusing. Here are some of those error messages:
At least one subscriber is associated to this group
Bad formatted ID
Managed object probably exists already
Cannot access Naming service. Is running ok?
Cannot contact Naming service. Is running ok?
Attempt to build a client request with a not supported yet request info type
Determine how the documentation will be delivered to the customer:
integrated with the software
If the documentation is to be integrated with the software, contact the system architect to discuss how the user will access it:
through a Help button on each GUI panel
through a menu item
through the F1 key
If the documentation is to be delivered on CD, plan how you will burn the CDs and label them. Determine whether users will need to dump the contents of the CD onto their hard drive before they can access the documentation. How will you convey this information?
If the documentation is to be delivered on paper, determine who will print and compile it. If a printing company, look for printers in your area and establish the lead-time required. If you, ensure that you have:
the required amount of paper
card stock for the covers and spines
For online help, determine what users will see after they click the Help button. Will they go to a topic that describes how to use a particular screen in the application? Will they go to a table of contents? Will they go to a Getting Started page? When creating online help, it is essential to plan how users will navigate through the help topics before you start writing.
Determine which desktop publishing software and help-authoring tool you will use. Order as required.
Work out the file structure and file-naming conventions for the documentation and online help.
For online help, work out the relationships among the different files. Will some help files be used for more than one GUI screen?
Create your templates.
The Writing Phase
Write your documents and make a list of glossary terms as you write.
During slow periods, research glossary terms using more than one source. (See Writing Glossaries for more information.)
During slow periods, research the correct wording for copyright notices of any third-party and proprietary products that you mention in your documentation.
When the documentation is complete, do a spell-check and review your work from cover to cover.
Send the documentation to the subject-matter expert (SME) for a technical accuracy check.
Make the required corrections.
Send the corrections back to the SME for verification.
The Delivery Phase
For documentation that is integrated with the application, talk to the system architect to work out the final details of integrating the documentation.
For documentation that is to be delivered on CD, burn and label CDs.
For printed documentation, print each document and insert in binders. Insert tab separators as required. Insert spines and covers.
The Archiving Phase
Name your documentation folder on the network with the product name and version number. If you will be updating the documentation in future versions, create a new folder with the new version name and copy all the documents there.
If your company has a document archiving system, use it.