Doc Writing

This is an introductory guideline for a team member who isn't a trained Technical Writer, but who is still helping to capture important information for the development and design effort.

Getting team members to capture and share info about the project is incredibly valuable ... Here are some basics that help make that info usable.

Scope

A big part of the tech writer's job is to make the software process that you describe understandable to the intended audience for the document. Your audience may include testers, managers, installation, operations & support personnel - even end users.

Remember: Neither the tech writer nor the ultimate audience for this document are likely to be as technically knowledgeable as you are.

Purpose

These guidelines are intended to help you write process descriptions that can easily be turned into documentation that is understandable to the intended audience. We can do that when you communicate your professional knowledge effectively. Here are some general guidelines that will help you to describe the process effectively:

Describe the Process Effectively

Provide a Context

The process you describe is part of a larger whole. The individual steps you're documenting make a lot more sense when you also provide some idea of the "bigger picture" of what's going on. A short paragraph at the beginning of the document should address:

Where does this process come from? Where is it going?
What does it do?
What does it depend on or interact with?
Who is involved? Who is affected?
How long does it take?

See The Big Picture

A picture is worth a thousand words. Can you describe the process as a chart or graph? Such an overview "snapshot" can be really valuable in helping your audience to understand. Don't worry about your artistry - Just get the process into an image. It's the tech writer's job to clean up the finished product.

Be Concise

Reduce complexity. Keep it simple. Fewer words = better. 'Nuff said.

Be Direct

Address the reader directly and use the "active voice" whenever possible.

For example:
"Click the [ Go ] button to start the application"

Not:
"The application process is allowed to be started by the operator's clicking on a button."

Be Explicit

The person who reads the document probably doesn't know as much about the system as you do. Make it as easy as possible for them to understand what's going on without guesswork.

Identify all elements and Label items clearly.
Describe events specifically.

Define Special Terms

A complex transactional process often involves multiple operations that are described in different ways (as a hardware unit, by software product, by alias, by operational role, as a system component, by database, as a client-side name, as a business role, etc.) This can be confusing to someone who doesn't know all the names and relationships by heart.

Be Consistent

Use the same terms and syntax (word order) whenever possible. For example: Don't call something a "frame" and a "panel" and a "box" and an "area" at different points in your writing. Just pick one term and stick with it.

Define your terms in the Glossary chapter.

Use consistent terms to describe objects.
Use consistent terms to describe relationships.
Use consistent terms and syntax to describe actions.

It's a dirty job, but somebody's gotta do it.