tl;dr:

Center the reader

Whenever possible, always frame the main topic in terms of “you” the reader rather than “me” the writer or “we” the company.

The simplest way to approach this is to take on the perspective of the reader and ask, “What’s in it for me?”

The reader is mostly not interested in what we are doing or our reasons for doing it. They want to know what they will get out of reading this article (and by extension, using this product).

This is especially important for titles, headlines, and introductions, because this is where you need to hook the reader and convince them to continue.

❌ We just released a new feature—look at what a great job we did.

✅ You can do amazing things with this feature—here’s why you’ll love it.

Use the present tense

Whenever describing an app’s processes or the order in which events take place in some code snippet, keep everything in the present tense.

❌ The callback will return a promise that resolves to the modified props.

✅ The callback returns a promise that resolves to the modified props.

Use active voice

<aside> 💡 In the active voice, the subject is performing an action:

The dog chases the ball.

Notice how the subject, dog, is performing the action, chase, on the target of the action, ball. This is a simple, direct example of the active voice.

In the passive voice, the action’s target, ball, is positioned first as the focus of the sentence. The sentence gets flipped, and the subject is now being acted upon by the verb. In other words, the subject is passive:

The ball is being chased by the dog.

—Grammarly, Active vs Passive Voice

</aside>

In general, active voice is preferred over passive voice because it’s more concise, direct, and focused on the reader.

The Grammarly article linked above shows that the grammar is more nuanced than “active is good and passive is bad,” but it’s good idea to err on the side of active over passive.

❌ The component’s DOM structure can be customized by using the component prop.

✅ Use the component prop to customize the component’s DOM structure. or

✅ Customize the component’s DOM structure using the component prop.