Writing tips for engineers

Recently I was asked for advice on what book to read to improve the writing skills. My companion needed this for engineers and other people whose jobs were not related to writing. Honestly, I didn't have an answer.

I've suggested developing the writing tips myself. First of all, that would increase the chance that engineers read them. I bet not many engineers are ready to find time to improve their writing skills. And secondly, that was an interesting challenge for me. I tried to look at writing from the engineers' lenses and analyzed some texts they wrote. I ended up with the idea that engineers should write the first draft in a way they can. But then the most interesting part will start when they edit. And my writing tips are here to help.

This is the general flow of how to evaluate the written text

Install the Grammarly add-on for your browser

This pure magic illuminates half of all the author’s problems.  

Before Grammarly	After Grammarly
	The FDLC (Feature Development Life Cycle) in Setapp consists of 6 steps. Each one serves a specific purpose.

Clarify ideas

Own ideas always look clear and transparent to us. But we should challenge them:

• May other people see something different here?

• Is there enough context?

• Do people understand all the terms?

Avoid long logical chains

Don’t make people jump from idea to idea, clause to clause. It’s difficult to follow long logical chains. People may forget what the sentence started from.

Tip: If your sentence contains multiple “to,” “and,” “which,” “that,” “for,” and other prepositions, most probably your sentence is overcrowded with logical chains.

Add senses and explanations

In the above sentence, we started talking about “this process” but didn't explain which process. We declared to specify the main idea but listed 5 different points. It’s also unclear why Setapp agreements are mandatory for the company and what knowledge should compose a library. These things require more explanations.

Missing explanations	Explanations added
The main idea of this process is to share agreements that are mandatory (including for company, product level procedures, and required by certificates) and tooling and knowledge that could be used as a library for best practices.	The main idea of the Feature Development Life Cycle (FDLC) is to share mandatory agreements for the product procedures. Agreements also define Setapp tooling and serve as a best-practices library. Note: Agreements must be aligned with the company values and meet certificate requirements.

Tip: Don’t hesitate to use longer text if it’s necessary for clarity.

Avoid long sentences

The average sentence length should be between 15–20 words. In most cases, the shorter, the better. Use these tips:

Drop unnecessary info

It is structured from a helicopter view with the primary purpose and roles overview to a more detailed description and links for additional information for specific practices.	It gives a helicopter view from general to specific.

Use bullets

It is structured from a helicopter view with the primary purpose and roles overview to a more detailed description and links for additional information for specific practices.

It is structured from a helicopter view: from primary purpose to a detailed description from roles overview to links on specific practices.

Add notes, tips, information, warnings

It is structured from a helicopter view with the primary purpose and roles overview to a more detailed description and links for additional information for specific practices.

It gives a helicopter view from the primary purpose and roles overview to a detailed description. Tip: Click links to find additional information on specific practices.

Implement standard writing recommendations

There are many, but I’ll list the most common ones:

1. Prefer the imperative and active voice. Avoid passive voice.

• This document could be used as a reference for best practices. (Passive)

• You can use this document as a reference for best practices. (Active)

• Use this document as a reference for best practices. (Imperative)

1. Don’t use epithets, synonyms, and other extras from fiction in tech docs.

• Imagine a user opens Setapp with a premonition of something incredible. Oh wow, the customer sees the thoroughly-designed My Explorer full of great features. (Fiction-style)

• A user opens Setapp. The customer sees My Explorer. (Usage of synonyms)

• A user opens Setapp. The user sees My Explorer. (Defined terms)

1. Mind English punctuation. See Punctuation Guide.

• The most used apps in Setapp are CCM, Bartender and CleanShot.

• The most used apps in Setapp are CCM, Bartender, and CleanShot.

• Click “See more”, if you need more information.

• Click “See more” if you need more information.

1. If you’re explaining a concept, provide an example or formula. This will simplify perception a lot.

2. If you introduce a new term, provide a definition even if you think that everybody knows this term.

P.S.

The Bible of tech writing in Apple is the Apple Style Guide. It’s really long and kind of boring. I don’t encourage you to read it just for fun. But if you’re in doubt about how to spell something, can’t sleep thinking of it, and are insistently searching for the truth — here is the link to the Apple Style Guide.