by Laura Tamayo

Created on: October 15, 2007

Technical Writing Be Organized, Clear, and Careful

The job of a technical writer is to organize complex information in a simple and clear way that can be understood by anyone. This goes beyond strong writing skills, like great spelling and perfect grammar. It takes someone who knows how to be organized, clear, and careful.

Be organized

You're starting with a complex set of instructions. You can save yourself a lot of work by starting out with a plan.

* Decide which sections or chapters you'll need.

* Start a style sheet to keep special terms, capitalization, and punctuation use consistent throughout.

* Make sure you know the method you'll use to deliver the final product (hard copy, CD, etc.) BEFORE you start writing.

* Know the format the user will have (binder, web page, etc.) when accessing the information.

As you start documentation, keep the style consistent. This means tone, order, and look of the information in each section.

You want your client to love you? Make templates! Including repetitive text (known as boilerplate text) will save time for you and anyone else working with the documents. With templates, you can change a word or phrase everywhere it appears automatically, instead of hunting down every instance of it individually.

And by taking the time to design your templates, you give detailed consideration to the visual impact. You want readers to intuitively navigate your documentation and find what they need without struggling.

Part of this ease-of-use is in the transparency of the file names you choose. Pick a logical and obvious name. No one should have to open each file to excavate information.

Adapt your file name strategy to fit in with the company's style, but without meaningless elements. So, for example, don't identify files by product number. Instead use a recognizable abbreviation. Avoid using chapter numbers in the name, since that doesn't even hint at what's in the file. Plus, the actual number may change as the project progresses.

So the product description and user guide files for a product called GBX might have names like this:
* GBX_pd.doc
* GBX_ug.doc

Make it easy for everyone to know which version they're looking at. Date the footer and include the version, such as 1.0 for the original.

If you make modifications to the original version of the documentation, adjust the date and version number, such as 1.3 for the 3rd edition. If there is a completely new release (say the product has been revamped), then mark that as well, with something like

• 1
• 2
• 3
• Next Page >>