Sticklers unite! You have nothing to lose but your sense of proportion, and arguably you didn’t have a lot of that to begin with
— Lynne Truss

Now that I am in my forties, for some strange inexplicable reason, use of grammar and consistency in written documentation has become more important than ever – Not to an extreme level of pedantry (I am sure that grammarians could rip this blog post to shreds), but the following, for instance, upset me more than is reasonable for a man who claims to be sane:

• The incorrect use of ‘their‘, ‘there‘ or ‘they’re‘ – This irks me
• Bullet points ending with random punctuation – They bother me
• Long rambling and somewhat incoherent sentences that prove the author has been practising their cut-and-paste skills – What do they think this conveys to the reader?
• Tables filled with useless boiler-plate information
• Spelling mistakes! Use the spell checker! It is built in for goodness sake!

The Solution

It is clear to me that a guide is needed to help authors write in a clear, concise and consistent manner. Why? I am glad you asked:

• Your audience expects a professional document. No ifs, no buts
• Documents, especially Statement of Works (SOW), require clear and non-ambiguous language
• It develops your understanding of the topic. When you are forced to consider every statement in your work, it creates a need to know your subject inside-out
• Not everyone is a native English speaker. When English is taught as a second (or third) language, students are expected to learn grammatical rules, exceptions to those rules and sentence construction – imagine then what happens when they come across documents containing colloquialisms, incorrect choices of homophones or phrases that qualify as TLDR (too long, didn’t read)?

We have to consider some realities when putting a style guide together though. It needs to be usable and useful to busy people. There is no point in insisting that the author should follow rules like:

• No prepositions at the end of a sentence
• No split infinitives
• Place a comma before a conjunction that joins two independent clauses

Fun fact: The first two in this list are considered as controversial in grammar as the use of the Oxford Comma!

What to do

Common sense dictates that text should be:

• Consistent throughout
• Clear, concise and precise
• Effective in its use of punctuation
• Relevant to the part of the document being read

Consistency

Consistency is king when writing formal documentation. Examples include:

• Place full-stops (periods) at the end of all bullet points, or do not. Choose
• Watch out for mixed Microsoft Word styles. Styles define fonts, their sizes and their spacing (along with other parameters). Do not mix styles; this is especially important if you cut-and-paste text from another document (inheritance)
• Define an acronym on its first use. Then use only the acronym from then on throughout the whole document
• Use Sentence Case or use Title Case in headings, but only use one or the other!

Clean and concise

Say what you have to say, but say it simply, clearly, and briefly. Then stop.

Think about each sentence and what message it conveys. Can it be taken another way than intended? Is it brief enough to communicate its message, but long enough to keep its meaning?

Punctuation

Punctuation is important:

“Now I must go and get on my lover” (original letter ending)

“Now I must go and get on, my lover” (hastily edited)!

— Ronnie Barker, Porridge

Also, do not use an ampersand (&) in formal documentation unless it belongs to a brand name. For instance, ‘Tiffany&Co.’ or ‘AT&T’.

Relevance

If a decision has been made for a project in a design document, tell me why!

Justify the decision – Do not write a generic response like ‘Security requirement’.

Your answer tells me nothing; more importantly, when we close a project off three months later in a Post-Implementation Review (PIR), will we understand what you meant? Was the justification correct, or should we do something else in a future project?

Consider your audience. Do you honestly know who will read your work? Does the document explain concepts clearly enough so that it can be understood by:

• Project Managers
• Technical staff
• C-Level executives
• Stakeholders

Conclusion

It is not easy being the guy that cares about grammar. For many people (including myself), grammar and punctuation were not really taught in school; there wasn’t any explanation of relevance, just rules to follow.

My view is this: The purpose of grammar, punctuation and relevancy is politeness and forethought.

You need to demonstrate to the reader that you care about their experience, that you want them to share the journey with you and that you hold yourself to a high standard.

For now, I will leave you with a favourite stickler quote…

From now on, ending a sentence with a preposition is something up with which I will not put
— Winston Churchill