Getting Better At Technical Writing 1: The Beauty of Consistency

Introduction

Getting better at technical writing requires lots of consistency. So, this article will focus on consistency.

Consistency, defined as the absence of contradiction, becomes essential when finalizing a written piece. The process of proofreading for inconsistencies is a crucial step in this regard.

This article provides readers with valuable tips on achieving consistency, drawing from a wealth of experience in commercial technical writing. The subsequent sections will delve into various aspects of maintaining consistency in writing.

Grammar Consistency

Before starting with a new writing endeavor, it is advisable to determine the target audience and the desired form of English usage.

For instance, “recognize” should be employed when addressing an English audience rather than “recognize.” Furthermore, it is imperative to avoid mixing British and American English within the same piece. An example of inconsistency is using “recognize” in Section 1 and “itemize” in Section 2.

Writers who employ software like MS Office or utilize devices with auto-prediction features should exercise caution. Certain software may predict spellings based on the user’s location or default settings.

Maintaining a consistent tense throughout the write-up is equally significant. The pronoun “I” should be used when sharing personal experiences or opinions. In contrast, “You” or “We” can be employed in tutorial guides to establish a sense of guidance. These pronouns are typically avoided in technical documents, manuals, and specific technical articles.

The subsequent section will explore the concept of Paragraph Consistency.

Paragraph Consistency

It is well-established that each paragraph within a written piece should maintain a consistent tone. Presenting multiple points within a single paragraph or spreading a single point across multiple paragraphs is considered unprofessional.

A recommended approach to structuring paragraphs is outlined below:

Begin with a sentence that outlines the key points of the paragraph.
Keep sentences concise and free from extraneous details.
While paragraphs can vary in length, maintaining paragraphs of 2 to 3 sentences is generally effective, although exceptions can be made for specific content.

As an illustration:

A proficient frontend developer should possess expertise in ReactJS. Merely understanding HTML5, CSS3, and JavaScript is insufficient for securing a frontend developer role. Most talent recruiters seek developers skilled in utilizing the ReactJS framework.

Style Consistency

Each section of this article has concluded with an introduction to the subsequent section, except for the preceding one. This intentional deviation highlights the concept of style inconsistency. Another example of inconsistency is the absence of Consistency as a prefix in consecutively related sections, as demonstrated in the upcoming section.

Regardless of the chosen writing style, adhering to it consistently is paramount.

This practice should be maintained if hyphens are used for word connections rather than indentation. For instance, “hard-earned” should not be followed by “easy-going.”

This convention should be consistently applied when emphasizing user interface elements through bold formatting (e.g., Click Save, then Exit).

If capitalization is employed across all words in a heading, this pattern should be replicated for all headings, particularly if they are interconnected. However, it’s important to note that very short words are not capitalized.

Whether employing commas, periods, or no punctuation at all for itemization, this pattern should persist throughout the entire write-up.

The following section will delve into the concept of Format Consistency.

Consistency in Formatting

Observant readers may have noted that the heading above appears slightly larger than the preceding headings. This deliberate discrepancy underscores the undesirability of Markdown inconsistencies.

Familiarity with Markdown—a skill inherent to most technical writers—reveals that an H1 tag was employed here, while H2 tags were used in previous headings.

It is imperative to uphold the chosen formatting pattern consistently throughout the writing.

Switching to bullet points should be avoided if numerical enumeration is selected for itemization.

Conclusion

While this article does not encompass every facet of consistency in technical writing, it equips readers to identify inconsistencies within written content. The presented principles are not rigid rules but best practices that contribute to continuous improvement.

The pinnacle of improvement is reached when an article is successfully drafted on the first attempt, requiring no subsequent edits. However, it’s crucial to acknowledge that this accomplishment is subjective. Technical perfection in message delivery may occasionally warrant a trade-off with minor grammatical or structural inconsistencies.