This content originally appeared on Level Up Coding - Medium and was authored by Anupama Pathirage
Recently, I took Google’s Technical Writing courses and found them filled with simple, actionable guidance that’s surprisingly relevant to everyday engineering work. It’s not overwhelming or overly academic — just practical tips that help you write more clearly and effectively, whether you’re working on product docs, design specs, or developer-facing guides.
In my earlier blog post, Beyond Code Reviews, I talked about why documentation matters, how engineering teams can take ownership of it without burning out, and how AI can support the process.
This post is a natural follow-up. I’m summarizing the key takeaways from Google’s course that helped me rethink how we approach technical communication — especially in product documentation — and how small improvements can make a big difference.
✍️ Writing Clear Words: Terms, Acronyms, and Pronouns
When writing for a technical audience, clarity is everything. Words that are perfectly clear to you might be confusing or unfamiliar to your readers, especially if they’re new to the topic, coming from a different background, or just scanning quickly.
Here are some simple but powerful guidelines to help your writing stay accessible and consistent.
📖 Define New or Unfamiliar Terms
As you write or review a document, watch for terms your audience may not recognize. When you spot one, use one of these two approaches:
- Link to a good existing explanation if the term is already well-known. Don’t reinvent the wheel.
- Define the term yourself if your document is introducing it.
If you’re introducing multiple new terms, consider adding a glossary to keep things organized and easy to reference.
Once you introduce a term, use the same word or phrase consistently. Avoid switching between synonyms or alternative names — it can confuse readers and slow them down.
🏷️ Shorten Long Names (Carefully)
When a product name or concept is long, it’s okay to define a shortened version to use throughout the rest of the document.
Just make sure you introduce the short form clearly:
Example: Protocol Buffers (or protobufs) provide their own definition language. …. And that’s why protobufs have won so many county fairs.
After the first mention, stick to the short version.
🔠 Introduce Acronyms the Right Way
Acronyms can save space — but only if they’re introduced correctly. Here’s how to use them:
- On first use, spell out the full term, followed by the acronym in parentheses.
- After that, use only the acronym throughout the document.
- Don’t switch back and forth between the full term and the acronym — it breaks reader flow.
Example: Representational State Transfer (REST) is an architectural style. REST allows APIs to…
When should you define an acronym?
Only when it meets both of these criteria:
- It’s significantly shorter than the full term
- It appears many times in the document
If an acronym shows up just once or twice, don’t bother defining it — it’ll just add clutter.
👤 Use Pronouns With Care
Pronouns like this, that, it, and they often refer back to something mentioned earlier, but not always clearly.
To keep things crystal clear:
- Replace vague pronouns with specific nouns
- Or, place the noun right after the pronoun to clarify what you mean
Unclear: “This is confusing.”
Better: “This error message is confusing.”
Unclear: “It fails under certain conditions.”
Better: “The authentication process fails under certain conditions.”
Clear pronoun use keeps your readers focused and helps prevent misunderstandings, especially in complex or technical explanations.
🗣️ Prefer Active Voice (Most of the Time)
When writing technical content, active voice is usually the better choice. It’s clearer, more direct, and easier for readers to follow.
Here’s why:
- Most people instinctively convert passive sentences into active ones as they read. Why make them do the extra work? Active voice removes that mental overhead.
- Passive voice often makes sentences feel vague or awkward. It hides the action behind unnecessary complexity.
- In many cases, passive voice leaves out who’s actually doing the work, forcing the reader to guess.
- Active sentences are typically shorter and punchier, which helps keep your writing tight and readable.
Use passive voice only when the actor is unknown, irrelevant, or obvious from context. Otherwise, let your sentences show who’s doing what — clearly and confidently.
🧹 Writing Clean Sentences
Good technical writing gets straight to the point. That means writing clean, direct sentences without fluff, filler, or vague language.
🚫 Avoid “There is” and “There are”
Sentences that start with There is or There are tend to be weak and indirect. They often pair generic nouns with generic verbs — adding words without adding meaning.
Whenever possible, cut the filler and let the subject lead the sentence.
Before: There is a variable called met_trick that stores the current accuracy.
After: The met_trick variable stores the current accuracy.
The second version is shorter, clearer, and easier to scan.
🚨 Be Precise, Not Promotional
Technical writing isn’t marketing. Your goal is to educate, not persuade.
Avoid vague adjectives and dramatic adverbs like screamingly fast or incredibly powerful. Instead, use specific, measurable terms whenever possible.
Before: Setting this flag makes the application run screamingly fast.
After: Setting this flag makes the application run 225–250% faster.
Facts help users make informed decisions. Fluff makes them second-guess your credibility.
✂️ Writing Short, Focused Sentences
One of the most practical lessons from Google’s technical writing course is this: short sentences are powerful.
Just as developers aim to write concise, maintainable code, technical writers should aim to write clear, efficient sentences that do one thing well. Here are the key takeaways from the course:
🧠 Focus on One Idea per Sentence
Long sentences often try to cram in too many ideas, which can confuse readers. Instead, break them into a series of short, focused sentences — each delivering a single concept.
🧹 Eliminate Filler Words
Wordy phrases make your writing bloated and harder to follow.
Before:
“An input value greater than 100 causes the triggering of logging.”
After:
“An input value greater than 100 triggers logging.”
🧩 Watch for Subordinate Clauses
Subordinate clauses add extra information but can bloat your sentence if misused. Apply the “one sentence = one idea” principle. If a subordinate clause introduces a new idea, break it into its own sentence.
Long:
“Python is an interpreted language, which was invented in 1991.”
Improved:
“Python is an interpreted language. It was invented in 1991.”
🔤 Know the Difference Between That and Which
If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don’t hear a pause, use that. Use a comma before which, but not before that.
The difference between that (used for essential clauses) and which (for nonessential ones):
Correct:
“Fortran is perfect for calculations that don’t involve linear algebra.”
“Python is an interpreted language, which Guido van Rossum invented.”
📝 Organizing Ideas with Lists
Good lists can transform technical chaos into something orderly. In fact, technical readers love lists — and for good reason. Lists break up walls of text, clarify relationships between ideas, and make scanning for information much easier.
Let’s look at how to use lists effectively in technical writing.
✅ Know Your List Types
There are three common types of lists in technical content:
Bulleted Lists — Use for unordered items — when the order doesn’t matter. If you rearranged the items, the meaning would remain the same.
Example:
You can install the CLI tool on the following platforms:
- Windows
- macOS
- Linux
Numbered Lists — Use when sequence or priority matters. Rearranging the items changes the meaning.
Example:
To set up the application:
- Download the installer.
- Open the setup wizard.
- Follow the prompts to complete the installation.
A great tip: Start each step in a numbered list with an imperative verb (e.g., Download, Open, Follow). This makes your instructions direct and actionable.
Embedded (Run-in) Lists
These are lists hidden inside sentences, and they usually hurt readability.
Example (not ideal):
“The API supports GET, POST, and DELETE operations.”
Where possible, convert embedded lists into bulleted or numbered formats to improve clarity:
Example:
“The API supports the following operations:
- GET
- POST
- DELETE
✨ Use Parallel Structure
For any list, make sure the items match in:
- Grammar (e.g., all start with verbs)
- Logical category (e.g., all configuration steps or all supported platforms)
- Capitalization (be consistent)
- Punctuation (especially for complete sentences vs fragments)
This parallel structure makes the list easier to follow and more professional.
💬 Always Introduce Your Lists
Before you present a list or table, include a short sentence to introduce it. Let readers know what the list represents or what to expect.
Example:
“To get started, complete the following steps:”
Well-crafted lists aren’t just formatting — they’re a key part of how technical content communicates effectively. Use them often, and use them well.
📚 Writing Better Paragraphs
A good paragraph isn’t just a chunk of text — it’s a self-contained unit of thought. Each paragraph should stick to one topic, one purpose, and one logical flow. If you’re talking about what’s coming up or rehashing what’s already been said, it’s a sign you may need to restructure.
🧠 One Paragraph, One Topic
Think of a paragraph like a well-written function: it should do one thing well.
Avoid wandering across topics or foreshadowing what’s next. Instead, keep each paragraph focused on the current idea. If you need to shift gears, start a new paragraph.
🧱 Avoid Walls of Text
Readers often skip long paragraphs, especially in technical documentation. A big, unbroken block of text feels like work. Most readers are looking to scan quickly and grasp concepts fast.
Stick to three to five sentences per paragraph. That’s the sweet spot.
🚫 Too long: More than seven sentences start to feel overwhelming.
⚠️ Too short: A bunch of one-sentence paragraphs makes the writing feel disjointed.
A well-paced document mixes paragraphs of varied but appropriate length, depending on the complexity of the topic.
🧭 Guide the Reader with Purpose
Strong paragraphs answer three key questions:
- What are you trying to tell the reader?
- Why is it important for them to know?
- How should they use or believe this information?
If your paragraph answers these clearly and concisely, it’s doing its job. In short: give each paragraph a purpose, keep it focused, and make sure it earns its place on the page. Your readers — and your future self — will thank you.
🧭 Stay Consistent: Use a Style Guide
No matter how well you write, your documentation won’t shine without consistency in punctuation, formatting, terminology, and tone. That’s where a style guide comes in.
A style guide acts as your team’s shared writing standard. It helps ensure that your docs:
- Sound like they were written by one team, not ten different people.
- Follow clear and repeatable conventions.
- Avoid unnecessary debates over phrasing, formatting, or naming.
If you don’t already have an internal guide, you can rely on some excellent industry-standard options:
These guides cover everything from capitalization rules to phrasing error messages to inclusive language practices. Even just skimming through them will level up your writing.
💡 Tip: Pick one style guide and stick with it. Consistency builds trust, improves readability, and saves everyone time.
🎯 Final Thoughts: Writing Is an Engineering Skill
Good writing scales your knowledge. It makes your decisions easier to understand, your designs easier to build on, and your team easier to onboard and support. Just like clean code, clear documentation is an investment that pays off every day — in fewer misunderstandings, better collaboration, and more confident developers.
If you’re an engineer, writing isn’t a chore — it’s part of your craft. So start small: review one document this week, clean up a README, or even better — take the Google Technical Writing course. You might be surprised how much of an impact a few better sentences can make.
Clearer Docs: Lessons from Google’s Technical Writing Training was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Anupama Pathirage
Anupama Pathirage | Sciencx (2025-08-19T16:14:44+00:00) Clearer Docs: Lessons from Google’s Technical Writing Training. Retrieved from https://www.scien.cx/2025/08/19/clearer-docs-lessons-from-googles-technical-writing-training-2/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.