Join Terri Wagner for an in-depth discussion in this video Reviewing essential technical writing skills, part of Developing Project Requirements.
- The purpose of technical writing is to help a specific audience to do something, understand something, or make a decision. Effective writing means we understand this audience, what matters to them, and what they expect to do with this information. Consider each audience in your requirements specification content and structure. The ability to communicate with your audience must be balanced with the need to specify requirements accurately and unambiguously.
Readers understand content by the context around it and by the document structure and framework. This is known as the given/new model. The given does not have to be defined or explained in your document. It may have been given in earlier parts of the document, known to the audience, or commonly known or embedded in the language. Other material is considered new. Your new material becomes more focused and effective when ample given information exists.
Working with the given versus new method means you don't have to explain everything every time. It's generally preferable to write in an active rather than passive voice. With an active voice, the subject of the sentence does the action of the verb. This approach focuses on the performer of the action helping to express the sentence content with greater vigor. For example, the committee reached a decision. With a passive voice, the subject of the sentence receives the action of the verb, and the performer of the action disappears.
For example, a decision was reached by the committee. This approach tends to emphasize the receiver of the action and will minimize the importance of the performer of the action. Let's talk about some other technical writing guidelines. Try to keep your sentences short. Only express one requirement per sentence. Avoid the use of jargon, abbreviations, and acronyms, unless you're completely confident that they'll be understood by all readers of your document.
Keep paragraphs short, no more than seven sentences, if possible. Use lists and tables wherever you can to present information sequences. Use words such as shall, should, will, and must in a consistent way with consistent meanings. So, if more than one person is responsible for writing the requirements, make certain you're all in sync and know how you're using these terms. If you're trying to express something that has complex relationships, diagrams tend to be more effective than attempting to describe in a natural language.
When possible, refer to other requirements, tables, or diagrams. Give a brief description of what you're referring to, as well as the reference number. Would you write the same way when describing technical requirements of the turbines to the designers versus describing customer capabilities to the end user electric companies you plan to link operations with? Look at some of the example requirements at a high level and decide how deep you can go into the technical specifications for a particular audience.
At some point, you need to draw the line between high-level system requirements that affect the users and low-level technical details for the designers and other folks.
Lynda.com is a PMI Registered Education Provider. This course qualifies for professional development units (PDUs). To view the activity and PDU details for this course, click here.
The PMI Registered Education Provider logo is a registered mark of the Project Management Institute, Inc.
- Classifying requirements
- Developing requirements
- Investigating requirements
- Documenting requirements
- Validating requirements
- Managing changing requirements