Get Better At Technical Writing: The Beauty of Consistency

Disclaimer

This is not a technical article, but a test article. If it proves helpful to you and you wish to see more like it, please drop a like and comment. I might be motivated to start a weekly newsletter on Getting Better At Technical Writing, or something similar.

Introduction

Consistency is the absence of contradiction. Whenever you conclude a write-up, it is imperative to go proofread it while checking for inconsistencies. In this article, I will give you tips on how to do this, based on the experience I've gained over years of commercial writing.

In the next section, I take you through Grammar Consistency.

Grammar Consistency

Before starting a write-up, you should have in mind who your audiences are or what type of English you wish to express in.
If you're writing for an English audience, you should use “recognise” and not “recognize.” Also, make sure to not mix British and American English in your write-up. Using “recognize” in Section 1 and “itemise” in Section 2 is an example.

If you write with an MS Office product or a mobile phone with auto-prediction switched on, you should be extra careful with this mistake. Some softwares use your location - or theirs - to predict spellings.

Sticking to a particular tone throughout your write-up is also important. When writing about personal experiences or opinionated contents, use “I.” When writing tutorial guides, use “You,” or “We” if you want the reader to feel held and guided. Technical documentations, manuals and some technical articles must be written without these pronouns.

In the next section, I take you through Paragraph Consistency.

Paragraph Consistency

It is no new information that each paragraph in your write-up must have one tone. Its unprofessional to raise two points in one paragraph and another point in a third paragraph.

A proper way I recently learnt to structure paragraphs is provided below:

• Start with a sentence that introduces everything your paragraph is going to say.
• Keep sentences short, and free of unnecessary contents.
• Having 2 - 3 sentences or paragraph is great, although some paragraphs might be occasionally longer.

For example:
A serious Frontend developer must have ReactJS in their repertoire. Knowing HTML5, CSS3, and JavaScript is not enough to land a job as a Frontend developer. This is because virtually all talent recruiters are searching for developers who know and use the ReactJS framework.

Style Consistency

I ended every section of this article with an introduction to the next section, except for the previous one. This is purposely to explain style inconsistency to you. Another inconsistency is not using Consistency as the prefix in a consecutively related section, like I did in the next section.

Whichever writing style you adopt, make sure to stick to it.

If you connect words with an hyphen instead of indentation, stock to it. Don't say “hard-earned” in Section 1 and “easy going” in Section 3.

If you bolden user interface elements (e.g. Click Save, then Exit), stick to it throughout.

If you capitalise all the words in a heading, you should repeat that for every other heading, especially if they are related. That said, you obviously know very short words are not capitalized.

If you use a comma, a period, or nothing at all at the end of an itemization, stick to this pattern throughout your write-up. For example, it's inconsistent having these two formats in one article:

In the next section, I take you through Format Consistency.

Consistency in Formatting

You must have observed that the heading above is a bit bigger than the others. This is purposely to explain to you that Markdown inconsistency is ugly. If you're familiar with Markdown - of course, every technical writer knows Markdown like the back of their hands - then you'd know I used an H1 tag here, and an H2 tag in the others.

Preserve whichever formatting pattern you adopt throughout your write-up.
If you use numbers for itemizing, don't switch to bullet points.

Conclusion

These are not everything you must know about Consistency in writing, but I am pretty sure you will be able to detect inconsistency in any write-up. These aren't rules, also, but best practices; we are all striving to get better.

You're getting better when your article ships on the first drafting, without any edits. Don't flatter yourself, this is subjective. If your message is technically perfect, it is sometimes a fair trade off for grammar and structure.

“Is it too much to ask for both?” - Tony Stark

Let me know what you think about this article, as I am skeptical of writing more.