Skip to content

The Technical Writing Process

May 23, 2011

The technical writing process consists of four phases:

  1. planning
  2. writing
  3. delivery
  4. archiving

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.

 

The Planning Phase

  1. Gather existing information—any or all of:
    • requirement specifications
    • functional descriptions
    • use cases
    • standards
    • contracts
    • etc.
  2. Determine which documents and other information you will create:
    • 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.

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.]

  1. 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
  1. Determine how the documentation will be delivered to the customer:
    • on paper
    • on CD
    • integrated with the software
  2. 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
  3. 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?
  4. 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
    • binders
    • tab separators
    • card stock for the covers and spines
  5. 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.
  6. Determine which desktop publishing software and help-authoring tool you will use. Order as required.
  7. Work out the file structure and file-naming conventions for the documentation and online help.
  8. For online help, work out the relationships among the different files. Will some help files be used for more than one GUI screen?
  9. Create your templates.

 

The Writing Phase

  1. Write your documents and make a list of glossary terms as you write.
  2. During slow periods, research glossary terms using more than one source.
  3. During slow periods, research the correct wording for copyright notices of any third-party and proprietary products that you mention in your documentation.
  4. When the documentation is complete, do a spell-check and review your work from cover to cover.
  5. Send the documentation to the subject-matter expert (SME) for a technical accuracy check.
  6. Make the required corrections.
  7. Send the corrections back to the SME for verification.

 

The Delivery Phase

  1. For documentation that is integrated with the application, talk to the system architect to work out the final details of integrating the documentation.
  2. For documentation that is to be delivered on CD, burn and label CDs.
  3. For printed documentation, print each document and insert in binders. Insert tab separators as required. Insert spines and covers.

 

The Archiving Phase

  1. 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.
  2. If your company has a document archiving system, use it.
  3. You are done!

source: http://www.docsymmetry.com/technical-writing-process.html

Advertisements
No comments yet

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: