Hey everyone! Welcome back to our series on technical writing. In our last lesson, we focused on embracing clarity; today, let's talk about its close cousin, consistency.

Imagine you're reading a user manual for a new piece of software. On page one, the button you need to click is called OK. On page three, it's called Confirm. And on page five, it's just ✓. Confusing, right? This is a classic example of inconsistency, and it can cause serious frustration for your users.

In technical documentation, consistency isn't just about good grammar; it's about predictability and trust. When your documentation is consistent, your readers know what to expect. They can learn your terminology and navigate your content with confidence, without having to stop and guess what you mean.

Why Consistency Matters in Docs

• Builds Trust: When your docs are consistent, it makes your product look more professional, polished, and reliable.
• Reduces Confusion: Users don't have to waste time figuring out if different terms mean the same thing.
• Improves User Experience: It makes your documentation easier to read and follow making the user journey smoother.
• Aids in Skimming: Consistent formatting helps readers scan documents quickly to find what they're looking for. Most people do not read docs completely end-to-end, they just skim them and look for answers to their questions.

The Pillars of Consistency

Let's break down consistency into 4 main areas you can start focusing on right now:

• Grammar and spelling
• Terminology
• Formatting
• Tone and Voice

1. Grammar and spelling

Can you catch the difference when you use the wrong “wear” (or is it where, we’re, were?) in your writing? Using correct grammar and spelling not only makes your docs look polished and well-written, it makes them easier to understand and to translate into other languages. With the growing use of AI summaries and agents, ensuring correct grammar is vital for clear and effective communication!

Spelling mistakes can be very embarrassing for the company and for you as the writer. So, always do a manual spell check even when you have spell-checker software that is excellent. 

Tip: Improving your grammar, not just in formal documentation but in your daily conversations, emails, and texts, is the most effective way to enhance your writing skills.

2. Terminology:

If you call a button Save in one place, call it Save everywhere in your tech docs. Create a small list of key terms or glossaries for your project and stick to them. This includes product names, feature names, and technical terms. You don't have to create a massive glossary overnight, just start with the most important terms and keep adding to it as needed.

3. Formatting:

How do you highlight code? Is it in code blocks? A different font? Make a decision and stick with it. Do you use bold for UI elements? It's your choice, but be consistent across all your docs. This applies to headings, bullet points, numbered lists, and even the way you use punctuation.

4. Tone and Voice:

Voice is the personality of your documentation. This remains consistent across all your content. The voice should be clear, direct, avoid jargon, etc. Tone can change based on the type of docs, for example a tutorial may use a conversational tone, whereas a troubleshooting guide may use a more direct and calm tone. Read more about it in the Google Developer Documentation Guide.

Actionable Tip: Start a Style Guide

The best way to ensure consistency is to create a simple style guide applicable to your team or organization. Does your company have a publicly available style guide? If yes, take inspiration from that or you can use many of the style guides available online as well.

You should document company- or team-specific nuances in your style guide. This doesn't have to be a 100-page document. It can be a simple shared document or a Notion page that lists your key terms, formatting rules, and preferred tone.

For example:

Tip: You can go a step further and add this style rules to your linter if you are following docs-as-code approach for your tech docs!

By focusing on clarity, you'll be well on your way to creating documentation that is not only clear but also trustworthy and professional. Good luck with your technical writing journey, think about what items you can put inside your style guide and start today!

Let me know in the comments what other writing-related topics you are interested in understanding.