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.
The Wireframes / DemoSite are not always rendered as a document, but they are closely related, re-useable design collateral.
Easy to Consume Most of the initial product-oriented documents are only a few pages.
The Library source materials themselves may be very large – since they serve the entire product suite. A subset of the Library source materials apply to the Product
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.
Reduce complexity. Keep it simple. Fewer words = better. ‘Nuff said.
Address the reader directly and use the “active voice” whenever possible.
“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.
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.
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.
I just make shit up. But I always write it down.
Documentation is a dirty job, but somebody’s gotta do it.
Define the terms most commonly used in your documents.
The object that initiates an action
- Drag the selected item from the source “Options” list.
The object that receives the action or the effect of the action.
- Send the selected data to the target “Execution” window.
The control or window that is the focus of activity
- By default, the focus is on the “User Entry” field when the “Active Record” window opens.
Start an app or open a window
- Click the Edit Active Record button to invoke the File Processor process.
press / type
Hit (or type) a key (keyboard entry)
- Press the Del key to delete the selected text in the “Record” field.
Invoke a button (screen action)
- Click the OK button to submit the data for processing.
Choose an option (from a list)
- Select the <menuitem> in menu <targetMenu>.
The chosen object
- <menuitemA> is the selected in menu <targetMenu>.
Common terminology helps establish consistency.
… of good collateral:
- Scale & scope lend themselves to an Agile “sprint” environment
Address specific needs
- Each document has a purpose
Responsibility for creation
- Each discipline contributes their own “voice” & perspective
Documents are linked by a common reference: the BizRule
- Easy cross-referencing across collateral
Across the product and across the enterprise (suite of products)
Customizable to breadth & depth of needs
- Audience can self-service information, based on need
Leveragable and reusable
- Easy flow of info into and out of Library collateral
© The Communication Studio LLC