This content originally appeared on DEV Community and was authored by Anne-Laure
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!
This content originally appeared on DEV Community and was authored by Anne-Laure
Anne-Laure | Sciencx (2024-06-18T08:14:43+00:00) Lessons from Google’s technical writing course for engineering blogs. Retrieved from https://www.scien.cx/2024/06/18/lessons-from-googles-technical-writing-course-for-engineering-blogs/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.