Most people don't think about what goes into the development of a technical document. They think 'Pfft, I could do that with one hand tied behind my back.'

Ah, poor innocent souls. :)

I am not talking about toaster manuals, although they are not without merit. I am talking about user guides, training manuals, procedures manuals, online help systems, and all of those other technical materials that make the software and hardware user's experience a little easier.

Bad writing vs. Good writing - Simplicity is Key

I have to say that there is some really bad technical writing out there, written by writers who believe themselves to be the Leo Tolstoys and Emily Dickinsons of technical writing. I have met more than my share of them, so I know whereof I speak. They think technical writing should be wordy and complicated, so they don't look like trained monkeys or idiots. It's not about the writer - I have never gotten a byline. So what? I get tremendous satisfaction knowing someone loves my materials and finds them useful, easy to follow and helpful. That's what it's all about, isn't it? Helping people understand something better? And the best way to accomplish this is to produce something clear, precise and easy to understand, using only necessary words - no fluff.

If your documentation is bad, you won't last long. Or you might, but users will complain about your stuff and before you know it, your stuff ends up on the trash heap.

As a freelance writer, I am no longer required to follow all of these steps, but I still do, continually checking and rechecking my work, because one misspelled word, one error, even one punctuation error will be noticed by your user and damage the credibility of your entire document. The first thing technical writers learn is to write for their audience, which means they need to identify who will be using their product, and how. I would just like to add that the best way to see if your writing does what it is supposed to is to use it yourself and walk a mile in those end-user moccasins, which helps you uncover hidden flaws and outright mistakes in your writing and many times, in the application itself.

The Lifecycle of a Technical Document

Most technical documents go through all of these phases in their lifetimes:

• Planning Phase
• Design Phase
• Writing Phase
• Editing Phase
• Printing Phase
• Final Editing/Revisions Phase
• Final Printing Phase
• Boilerplate Phase
• Product Release Phase

So, here is all of the work that goes into a typical document:

The project manager meets with engineers or product development personnel, marketing people and assorted managers to introduce the product, which is in its development stages, to describe it, identify users (audience) and their documentation requirements, which can range from design documents and technical specs (for the engineers), white papers (for management and marketing personnel), training manuals, user guides, online help systems (for end-users, e.g. administrative, clerical or technical support staff), web content (for internal staff or the general public). Other meetings splinter off from this initial meeting, and that is when the fun begins.

Step 1 - Writers meet with engineers and management teams to determine who does what. Then another meeting is set to discuss which standards and conventions will be incorporated into the deliverable. If there are none that apply to this particular document, then writers are tasked to create style standards that will best enhance the document in terms of usability and overall look and feel.

Step 2 - The writer meets with engineers for a crash course in how the new product will work, which is usually a software application (GUI interface or some other tool), or hardware (such as a POS (Point Of Sale) keypad), or overall changes to a design system. Obviously writers aren't going to understand the nitty gritty of incredibly complex systems, but they can glean enough to write about it from the user's perspective.

Step 3 - From notes, the writer enters the narrative into a computer, usually Microsoft Word, beginning with a high-level (broad) summary of how the application works, then begins describing in detail how to use it, in a step-by-step format. At this point, no images are included and no styles are applied to the document. This bare-bones document is printed out, given a cover sheet stamped "ROUGH DRAFT", initialed by the technical writer and given to the engineer to review. At this point the engineer should have a healthy percentage of the actual application completed and will have conducted beta testing on the application, which means they operate the application to see if it works as designed. Then the writer conducts their own beta test of the application from a user's perspective, where they will capture screen shots of it for inclusion into the user guide.

Step 4 - The writer formats and incorporates the screen shots and other images into the document, along with the changes the engineer makes, as well as new information, and begins the formatting and editing phase. During this phase, the document goes through online editing as well as hardcopy (printed page) review by the writer, checking every design element of the document including logical flow, correct numbering streams, look & feel, consistency, etc.

After all editing is completed, the document is printed out with a cover sheet stamped "DRAFT", initialed and presented to engineers, managers and marketing personnel for their input.

When the development of the product is complete and no more changes to the operations or look & feel of it are anticipated, the engineers and other managers and marketing personnel mark the document with their changes, or add additional content to be incorporated (only after agreed on during meetings with all project participants), then the document goes back to the writer for the final editing/writing phase.

Step 5 - Final Editing/Writing Phase

The writer incorporates all of the changes, revisions and new content into the Micosoft Word document and repeats the editing process all over again, only this time they use printed forms called checklists, which contain specific design elements that must be verified and adhered to. Each element of the document is checked, and there are checklists for each type of element:

Styles and Conventions (Look & Feel), including correct wording, such as "Displays the ABC dialog box" as opposed to "A window appears", image size and placement, bulleted list items such as dots as opposed to diamonds, etc., and adheres to set style rules of the company and others such as the AP Stylebook or the Chicago Manual of Style; whichever one the company uses.

Numbering Streams, including figure captions, sequential numbering of steps and pages.

Logical Flow, including analysis of the narrative, steps and procedures to ensure that it flows smoothly and makes sense.

Punctuation, Spelling and Grammar, which includes running a spell-check, and making sure punctuation is correct and narrative is written in the active voice and is grammatically correct.

Consistency, which verifies that all application components are referred to in the same way throughout the entire document (e.g. "window", "dialog box", "menu", etc.), and Help topics are worded in the same way, e.g. "How do I?" not "How to", etc.).

Hardcopy Edit, in which the entire document is printed out, where any flaws in layout and formatting are corrected, including making sure that odd pages always begin on the right page, entries in the Table of Contents are checked against corresponding pages, etc.

The checklists are designed to be used for one type of edit at a time to ensure that you are focused on that specific element, which cuts down on overall errors throughout the documentation process, so basically, one type of edit is done for each group of design elements. When final changes and revisions are completed, the document is printed out and goes back to everyone for final approval and prepared for the 'boilerplate' phase.

The term 'boilerplate' dates back to the early 1900s, referring to the thick, tough steel sheets used to build steam boilers. From the 1890s onwards, printing plates of text for widespread reproduction such as advertisements or syndicated columns were cast or stamped in steel (instead of the much softer and less durable lead alloys used otherwise) ready for the printing press and distributed to newspapers around the United States. They came to be known as 'boilerplates'. Until the 1950s, thousands of newspapers received and used this kind of boilerplate from the nation's largest supplier, the Western Newspaper Union. Some companies also sent out press releases as boilerplate so that they had to be printed as written. The modern equivalent is the press release boilerplate, or "boiler," a paragraph or two that describes the company and its products.
-source: Wikipedia

Final FINAL Phase (Or IS it?)

The writer incorporates all final approved changes and electronically 'tags' items from each page that are relevant and that they think a user would search on when using an index, and the Index is created and added to the document. The writer adds supporting Appendices and cover pages, and verifies dates, titles, and copyright information and generates a new TOC (Table of Contents), verifies that all page numbers are correct, as well as index references and prints the FINAL final copy for FINAL final review. The document is printed out with a cover sheet stamped "FINAL DRAFT", initialed and presented to engineers, managers and marketing personnel for their input.

At this stage of the game, the document is pretty clean, with few errors, since it has undergone such stringent review. It is still necessary to have everyone look at it one more time to make sure everything is as it should be.

Then the document is marked with a cover sheet labeled "BOILERPLATE' and sent to an offsite vendor who binds the document according to a predetermined format, such as books or binders embellished with the company name and logo, and slick and colorful graphics. They print one copy for each team member, who looks over the 'prototype' of the actual product that the client will be receiving, then when everyone agrees it looks great, the writer and department manager give the vendor the green light to print hundreds of copies for distribution.

Even at this stage, omissions or errors can still appear, in which case the writer must add Release Notes, errata or addenda to the final product at shipping to alert the customer. We usually hate to see those though, as they directly reflect on the overall credibility of the document.

Ever notice when you read a user guide you never see "written by John Doe"? That is what a byline is, and even though you can spend many hours developing something this huge, you will never see your name anywhere on it. As a user, I know I don't care who wrote it - I just care that it helps me and makes sense.

You have to really love words, or maybe even be a little OCD, even to subject yourself to such precise and microscopic management of yourself and your work, but precision pays off in the end.