Did you ever read a project document and immediately recognize that it was written by many different people? It can be easy to tell when we stick together different sections of our documents that were written by different authors. Sure would be nice if all of our project documents looked like they were written by one person, even if that one person is actually several members of the project team. To achieve this, I recommend that every project team use a style guide to define how they will write the contents of their project documents. A style guide is a great way to define your team’s writing style, diction and grammar use so our documents are more cohesive and more readable. Some organizations have style guides that folks use across all types of documents. Other organizations don’t have anything like this. Style is the “technical issues” within your documents, governing your team’s use of acronyms, capitalization, punctuation, numbers, structure and basic grammar. Let’s take a closer look at these items and how we might address them using a simple style guide.
Acronyms can be confusing to your readers if they don’t know what they stand for. Every organization seems to have its own version of this “alphabet soup”. Sometimes you can have the same letters in an acronym that stand for two entirely different things. One best practice is to spell the acronym out on its first use in any document. You can also include an acronym list at the end of your document for your readers.
Capitalization can be done in a variety of ways within a project document. The team needs to decide whether or not they will capitalize proper nouns, names, titles or other words. Once we know the rules, everyone needs to apply them consistently. I once worked on a project where we wrote our requirements document and upward capitalized every user type just to make sure that our readers paid closer attention to who was involved with the capabilities we were defining.
Punctuation offers a lot of challenges in a project document. The team needs to decide things like whether or not to use a comma after the next to last item in a list, right before the “and”. Then we all need to do it the same way. Are we listing items in our document like “… one, two, and three…” or are we listing like “… one, two and three…” For the sake of our document readability, we need to use punctuation correctly and consistently.
Numbers are also an interesting topic in our documents. Do we use the numbers themselves, do we spell out their names or do we use some combination of the two? For example, do we use the numbers like 1, 2, 3, 4, 5, 6, 7 and so on or do we spell them out like one, two, three and so on. Or we could choose to spell the numbers out from zero through ten and then use the actual numbers for 11 and above.
Structure is the way we decide to put the pieces and parts of our documents together and build their contents. I am a big fan of using project document templates and outlines for common project documents to be consistent in how things are structured and what content the documents contain. You also need to decide about sentence structure and what’s allowable. For technical writing, I think simple sentences and plain language are the way to go.
Grammar is the system of rules defining our language structure. It is the way we use our words, what their functions are and how we put together their relationships within a sentence. One grammar decision we need to make when writing a project document is whether we all use active or passive voice. Active voice means that the subject of the sentence does the action of the verb, focusing the reader’s attention on the performer of the action (who does what). Here’s an example of an active voice sentence: “The committee reached a decision.” Passive voice is where the subject of the sentence receives the action of the verb versus performing that action themselves. In passive voice, the performer of the action sometimes disappears or is hard to discern. Instead, passive voice sentences emphasize the receiver of the action. The previous sentence can be written this way: “A decision was reached by the committee.” Which one would your readers prefer?
There are many style guides out there for the project team to use, ranging from the massive Chicago Manual of Style to a very nice technical writing style guide that I like very much, The Handbook of Technical Writing. Many industries have industry-specific style guides, as do many organizations. There are country-specific style guides out there as well. If you don’t have a project-level style guide, the team can easily build one for themselves.
In addition to the style guide items I have already discussed, you may want to consider including some or all of these elements in your project’s style guide:
Remember that your goal is high-quality, readable and understandable project documents across the project life cycle. Sometimes using equations, diagrams and other graphical forms of communication can be clearer than using words, so our style guide will need to address how we use those as well.
If you are looking to refine or define your technical writing skills for your projects or organization, consider Learning Tree’s 4-day introductory course on technical writing. Happy project documenting!