DEV Community: Anne-Laure

Lessons from Google’s technical writing course for engineering blogs

Anne-Laure — Tue, 18 Jun 2024 08:14:43 +0000

As a technical content writer helping engineers write blog posts, I recently completed Google’s technical writing course. While the primary purpose of this course is to assist engineers in writing technical documentation, I find that some of the advice also applies to engineering blogging.

By implementing the principles taught in this course, engineers can enhance their blog posts, making them more accessible and engaging for their audience. They will be able to better communicate their ideas and concepts, as well as increase their overall visibility.

Here, I will detail the advice I found most useful when it comes to engineering blogging.

A brief demonstration

To give you a taste of what Google’s technical writing course has to offer, let’s apply the advice to a short text first.

Consider the following technical blog post extract, revised using tips gleaned from the course…

Original: “It was supposed to be an exciting project. But the development team and the product team encountered issues when discussing the new ANN. They realized that the documentation was lacking, which made it difficult for them to understand the functionality. Concerns about the scalability of the system were also noted; and there was a need for further testing to ensure that all components work together seamlessly. Additionally, there was a lack of clarity regarding the roles and responsibilities within the team.”

Enhanced: “The development team and the product team faced challenges discussing the new artificial neural network (ANN). The development team realized that incomplete documentation hindered their understanding of its functionality. Concerns about system scalability arose as well. Extensive testing was necessary to ensure seamless integration of all components. Additionally, ambiguity persisted regarding team roles and responsibilities.”

Are you convinced?

Let’s review the improvements made to the original text one by one:

Acronym usage: In the original text, the acronym “ANN” was used without prior introduction of its full form, “artificial neural network.” Therefore, in the enhanced version, we wrote out the full term followed by the acronym.
Ambiguous pronouns: The pronoun “they” could refer to either the development team or the product team. In the enhanced text, “they” is replaced with “the development team,” providing clarity and ensuring that readers understand who is being referred to.
Active voice: The original text contained a passive voice construction, which can make sentences less engaging and direct. So “Concerns about the scalability of the system were also noted” was replaced by “Concerns about system scalability arose as well.”
There is/there are: The usage of “there was” sentence structure has been reduced to make the sentences more appealing.
Opening sentence strength: The opening sentence in the original text lacked clarity and failed to establish the central idea of the paragraph effectively.
The semicolon was not used correctly in the original text as it separated two independent thoughts. A period replaces it in the enhanced text.
Style guide consistency: “Artificial neural network” is written in lowercase in the enhanced text to follow the Google style guide, which prefers lowercase for terms that are not proper nouns.

Having said that, if you have a few more minutes to spend with me, I would like to review each piece of advice in more detail…

Use acronyms properly

When first using an unfamiliar acronym in an article, write out the full term followed by the acronym in parentheses. After this, you can use the acronym alone.

For example:
“This manual is for researchers new to the artificial neural network (ANN) or those needing to optimize ANN parameters through programming scripts.”

But should you systematically use acronyms?

Acronyms can shorten sentences, of course, but they can add a layer of abstraction, requiring readers to mentally expand them to their full form, which can take longer to process.

Consider these rules when deciding whether to use an acronym:

Is the acronym significantly shorter than the full term?
Does the article contain multiple references to the acronym?
Is the acronym central to the main topic?

On the other hand, remember that spelling out an acronym doesn’t always help the reader understand it. If you write out “portable document format” instead of “PDF,” the reader will not understand what it is. In other words, not all acronyms should be spelled out.

Avoid ambiguous pronouns

Ambiguous pronouns can create confusion in technical writing, as they may refer to more than one antecedent or be unclear about what they reference.

For instance, consider the sentence: “When the engineer talked to the developer, they explained the problem.” It’s unclear whether “they” refers to the engineer or the developer.

Here are some guidelines for pronoun usage:

Use pronouns only after the noun has been introduced.
Make sure the pronoun is as close as possible to the corresponding noun. If your noun and pronoun are separated by more than five words, consider repeating the noun instead.
Whenever you introduce a second noun between your noun and pronoun, use your noun instead of a pronoun.

Choose the active voice over the passive voice

Use the active voice as much as possible. Use the passive voice with caution.

The active voice offers the following advantages:

The majority of readers mentally convert the passive voice into the active voice.
The passive voice obscures your ideas.
Sentences using the passive voice sometimes leave out the actor entirely, which leaves the reader guessing who they are.
In general, active voice sentences are shorter than passive voice ones.

Reduce the number of times you use “there is”/“there are”

Sentences that start with “there is” or “there are” combine a generic noun with a generic verb, which doesn’t keep the reader hooked. Provide your readers with an actual subject and verb.

As an alternative, you could simply delete “there is” or “there are” (along with another word or two later in the sentence).

For example, consider the following sentence…

Original: “There is a significant difference between theory and practice.”

Enhanced: “A significant difference exists between theory and practice.”

In other situations, starting sentences with “there is” or “there are” avoids the hassle of creating true subjects or verbs. Replacing them with a meaningful subject creates a clearer experience for the reader.

Original: “The updates are not guaranteed to be received chronologically.”

Enhanced: “Clients might not receive the updates chronologically.”

Write a strong opening sentence for paragraphs

The opening sentence is one of the most important ones in a paragraph. Busy readers tend to focus on opening sentences and skip what comes afterwards. The central idea of a paragraph should be established in the opening sentence.

Original: “A block of code is any set of contiguous code within the same function. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.”

Enhanced: “A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.”

Use punctuation appropriately

Periods

Periods are used to separate independent thoughts.

Example: “The engineers completed the structural analysis of the bridge. They then proceeded to finalize the detailed design plans.”

Commas

Commas indicate a pause between parts of a sentence.

Examples:

Items in a list: “We need to purchase servers, storage devices, and network cables.”
Introductory phrase: “After analyzing the data, we made the decision.”
Non-essential information: “Our software, which is open-source, is highly customizable.”

Semicolons

Semicolons link closely related independent clauses.

Example: “The application crashed; the server needed a reboot.”

To be noted: The thoughts before and after the semicolon must both be grammatically complete sentences.

Em dashes

An em dash indicates a longer pause than a comma.

Example: “The new feature — while not perfect — has significantly improved user experience.”

Parentheses

Parentheses enclose additional information or asides that are not essential to the main point.

Example: “The new protocol (which we tested extensively) has been implemented.”

Adopt an established style guide

A style guide ensures consistency in your writing, covering aspects like tone, terminology, formatting, and punctuation. Adopting a style guide can help maintain a professional and cohesive voice across all your blog posts.

Style guides are time-consuming to set up and maintain, so it is recommended to adopt a recognized one and modify it as necessary.

Popular style guides for an engineering-focused audience include:

Going further

In conclusion, Google’s technical writing course offers valuable insights applicable to engineering blogs. By implementing the principles learned, engineers can increase their audience engagement.

To take things a step further, make sure before you write your blog post to understand and define your target audience to ensure that your content is tailored appropriately. Adapting your language, depth of explanation, and content structure accordingly ensures that your message is clear and relevant. So before writing, always ask yourself: Who is my primary audience? What level of knowledge do they have about the subject? What information do they need to know? How can I present this information in a way that is engaging and easy to understand?

If you want to improve your technical writing with additional tips, don’t hesitate to consult the Google technical writing course!

My top 7 tips for engineers who want to write their first blog post

Anne-Laure — Tue, 04 Jun 2024 11:17:45 +0000

I kicked off my career journey as an IT project manager, but my curiosity led me down exciting paths into coding (especially front-end and iOS) before moving into journalism.

Over the past 6 years, I've had the pleasure of supporting numerous developers and engineers in French tech companies with their blog writing initiatives. From polishing up posts to collaborative writing sessions and even crafting pieces from scratch based on their ideas, I've been there every step of the way.

Now, let's jump right in! Here are my top 7 tips that I love sharing with the developers and engineers I work with.

Sharing is a state of mind

Finding inspiration for blog post topics can strike at any moment, so it's wise to capture those ideas as they come. Whether you're brainstorming during lunch, in a meeting, or even in the bathroom, write down those thoughts promptly. Personally, I rely on the Notes app on my iPhone, but use whatever tool suits you best. The key is accessibility, ensuring you won't forget those creative sparks. Then, when it's time to write, you'll have a ready-made list of ideas to choose from.

Once your post is written and published, your work has only just begun. Especially if you're not yet a household name in the developer world, sharing your post is crucial. Whether it's on social media, through a newsletter, or on a content curation platform, getting your work out there matters. If social media is your choice, adding a personal touch to the link can make all the difference in engagement.

But don't stop at just sharing — leverage your research and writing efforts further by responding to Calls for Papers (CFPs) and offering talks on the same topic. Adapting your article into a presentation may require some additional effort, but it's far less daunting than starting from scratch. And remember, it goes both ways — your talk can inspire your next written piece just as your article can fuel your presentation.

Understand your audience

Before you start writing, think about who your readers will be. Are they beginners, intermediate, or advanced engineers? Tailor your language, content depth, and examples to suit their understanding level.

When writing for beginners, it's important to use clear and simple language. Avoid technical jargon and explain complex concepts in a way that is easy to grasp. Additionally, provide plenty of examples and visuals to illustrate your points.

Using visuals and code examples benefits everyone because it helps visualize abstract concepts and understand them more easily. It also caters to different learning styles. Some individuals are visual learners, meaning they learn best through images and diagrams.

Topic !== angle

An article cannot cover all aspects of a topic. Attempting to do this could result in a 5,000-word post that would be difficult to read. In order to tackle your topic effectively, you must choose an angle — and stick with it!

To illustrate this, let’s take a concrete example. If you want to discuss Python testing in your post, for instance, the angles could include:

The historical angle: Tracing the evolution of Python testing methodologies over the past decade.
The practical angle: Tips for testing Python code effectively.
The feedback angle: A journey through the Python code testing methods used in your company.
The news angle: Spotlighting the newest libraries and tools designed for testing Python code.

Some people put everything they can think of in their blog posts without considering an angle. They think more is better, but it doesn’t work like that. Others tend to systematically select the same angle: the feedback approach. Well, sometimes it’s the best angle to use to tell a story, but not always. Considering the angle before you start writing will save you a lot of time and make your post more engaging.

Be explicit

Imagine picking up a piece of string that symbolizes your thoughts and holding it tightly in your hands while writing the blog post. And don’t drop it!

You should always ensure there’s continuity in your writing. Whenever you switch between ideas, you must clearly explain why. E-v-e-r-y time. Reading your text out loud can be very helpful with this. It allows you to identify gaps in your thought process or missing information.

And since it is the first thing your reader will see after the title, the introduction to your blog post should be the most explicit part of all. Make sure it provides some context, as well as an explanation of who the target audience is, why you have the authority to write it, and what the reader should expect to find in it.

Spend time on your headings

Your blog post’s title will be the first item readers will notice. This is what will make them click on your article (or maybe not!). It is so important that finding the right headline should be a separate step in your writing process. You should spend time on it and involve your reviewers in the decision making. To brainstorm titles, tools like ChatGPT can be very helpful. My recommendation is to put forward three to five proposals for your reviewers to choose from.

Subheadings should not be overlooked either. In addition to helping structure the post, they facilitate quick reading. Make sure your headings are not too generic and be as descriptive as you can so people know what they’re going to be reading next. For example, if you’re describing the 10 steps of your migration plan in a section of your article, naming it just “Steps” might not be the best idea. There is usually going to be a better subheading, like “A 10-step migration plan”.

Timing is key

To choose the most appropriate angle for your topic, you should consider the stage of the technology you’re discussing. You can use the Gartner hype cycle to help with that (thanks, Crafts Records, for the inspiration). Essentially, this model is a graphical presentation that displays the maturity, adoption, and social application of specific technologies.

The most common categories of technical blog posts include:

A brief introduction to a new technology that you’ve just discovered.
Things you wish you’d known one year ago or as a junior.
Resolution of the pain points spotted around you.
Feedback about the implementation of a technology.
Postmortems.
An explanation of your strongest convictions.
Notes from conferences/meetings.

Among those blog posts, some will be more relevant at certain points in the evolution of technology. For instance, the introduction to a technology will be more appropriate between the Technology Trigger and Peak of Inflated Expectations phases, while feedback will be better suited to the period that follows, when the technology is often decried. The Plateau of Productivity phase is often the best time for expert posts on specific technology details.

Include peer review into your proofreading process

Include reviewers in your blog post proofreading process, just as you would with your code. There is no need to involve too many people in the process — 2 or 3 is usually enough. To efficiently incorporate reviewers' feedback, establish a clear system for tracking and addressing comments. Use a collaborative document-editing platform where reviewers can leave comments directly in the document.

In addition, tools like Grammarly, Hemingway or Wordtune can help with grammar and readability. These tools can catch errors missed by human reviewers, ensuring your content is error-free and easy to read. They can also provide valuable suggestions for improving your writing clarity and coherence.

Finally, take a break after writing and revisit your blog post with fresh eyes. Reading your text aloud can help you identify any awkward phrasing missed during the initial writing process.

This is the conclusion you should never write

A conclusion usually summarizes what has been discussed in the post and talks about what is to come. When writing the final paragraphs, most people are tired and just want to finish their post. Let’s face it, conclusions are often sloppy.

Start by avoiding giving your conclusion the subheading “Conclusion”. Whenever possible, it is better to find something that has more meaning. And keep in mind that your conclusion will be the last thing your readers remember. So if there is a place where you can be creative about making an impression, this is it!