1. Playbook
  2. Dojo

Technical Writing

As a software engineer, you read a lot more than you write. This written communication doesn't happen only through code – you write in Google Chat, in issue trackers, in documentation pages, and even in Git commits! Thus, it is important to communicate effectively in English as well. Remember that many readers are not native speakers of English, so please be thoughtful with your colleagues, and take extra care when proofreading.

Google recently released a short course on Technical Writing. When you have a few spare minutes, you can browse it, take notes, and start practicing the guidelines.

Google Technical Writing
Source: https://developers.google.com/tech-writing

Recommendations

Here, you will find a shortlist of their recommendations:

  • Use terminology—including abbreviations and acronyms—consistently.
  • Recognize and disambiguate pesky pronouns.
  • Distinguish active voice from passive voice.
  • Convert passive voice sentences to active voice.
  • Identify three ways in which active voice is superior to passive voice.
  • Develop at least three strategies to make sentences clearer and more engaging.
  • Develop at least four strategies to shorten sentences.
  • Understand the difference between bulleted lists and numbered lists.
  • Create helpful lists.
  • Create effective lead sentences for paragraphs.
  • Focus each paragraph on a single topic.
  • State key points at the start of each document.
  • Identify your target audience.
  • Determine what your target audience already knows and what your target audience needs to learn.
  • Understand the curse of knowledge.
  • Identify and revise idioms.
  • State your document's scope (goals) and audience.
  • Break long topics into appropriate sections.
  • Use commas, parentheses, colons, em-dashes, and semicolons properly.
  • Develop beginner competency in Markdown.

Key Highlights

We still have a lot to learn, so please submit pull requests if you learned something already applicable to existing documentation. The following is a non-exhaustive list of things to pay special attention:

Master Your Language

At Datopian, you will be writing software and documentation that routinely impact millions of people. For that reason, you want to ensure to get your message across – and that includes an excellent use of the English language.

The first recommendation on that matter is to get yourself a Grammarly account. Grammarly is a smart spell checker, notifying you not only of typos, but on the use of complicated sentences, and uncommon word combinations. You can start with a free account, but the premium subscription will guarantee better results in the long term.

Google Technical Writing
Source: https://www.grammarly.com/blog/comma/

After mastering the most common mistakes and corresponding corrections provided by Grammarly, you may want to get to the next level. Our recommendation is the Academic English: Writing Specialization, by the University of California, Irvine. The first two courses will expose you to the grammar rules behind Grammarly's intelligence. With enough effort, you will become better than the service and might even be able to cancel the premium subscription.

Learn More

Are you still eager to learn more about this subject? You can start by the studying the following pages: