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.
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.
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
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?
Address the reader directly and use the "active voice"
"Click the [ Go ] button to start the application"
"The application process is allowed to be started by the operator's clicking on a button."
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.
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.