Documentation, white papers, online help, user guides, quick start guides, web site content, marketing materials
The technical writing process consists of four phases:
1. planning
2. writing
3. delivery
4. archiving
The Planning Phase
1. Gathering existing information—any or all of:
- requirement specifications
- functional descriptions
- use cases
- standards
- etc.
2. Communicating to the client which documents and other information will be created:
- product descriptions
- installation guides
- configuration guides
- system administration guides
- alarm-clearing procedures
- routine maintenance procedures
- command reference guides
- online help
- error messages
- notifications
- tooltips
- etc.
3. If the documentation is to include tooltips, error messages, notifications, and dialog boxes, our technical writing staff will develop a plan to ensure that the wording of these is consistent, clear, and grammatically correct.
4. Discussing with the client how the documentation will be delivered to the customer:
- on paper
- on CD
- integrated with the software
5. If the documentation is to be integrated with the software, we 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
6. If the documentation is to be delivered on CD, we discuss with the client how to burn and label the CDs and determine whether users will need to dump the contents of the CD onto their hard drive before they can access the documentation.
7. If the documentation is to be delivered on paper, we determine who will print and compile it. If printing and compilation is to be consigned to a printing company, we look for printers, establish the lead-time required and ensure that the printer has:
- the required amount of paper
- binders
- tab separators
- card stock for the covers and spines
8. For online help, we determine what users will see after they click the Help button.
9. Communicating with the client which desktop publishing software and help-authoring tool you will use. Order as required.
10. Working out the file structure and file-naming conventions for the documentation and online help.
11. For online help, we work out the relationships among the different files and determine whether some help files will be used for more than one GUI screen?
12. Creating templates.
The Writing Phase
- Writing documents and make a list of glossary terms.
- During slow periods, we research glossary terms using more than one source.
- During slow periods, we research the correct wording for copyright notices of any third-party and proprietary products that you mention in the documentation.
- When the documentation is complete, we run a spell-check and review work from cover to cover.
- Sending the documentation to the subject-matter expert (SME) for a technical accuracy test.
- Making the required corrections.
- Sending the corrections back to the SME for verification.
- For documentation that is integrated with the application, we talk to the system architect to work out the final details of integrating the documentation.
- For documentation that is to be delivered on CD, we burn and label CDs.
- For printed documentation, we print each document and insert them in binders, insert tab separators as required, and insert spines and covers.
The Archiving Phase
- Naming your documentation folder on the network with your unique product name and version number. If the documentation will be updated in the future, we create a new folder with the new version name and copy all the documents there.
- Project done
|