Technical Writing Best Practices for Engineers

Chapter 1 · Practice 3 of 4

State the scope, the non-scope and the key point at the start

From Know your audience and purpose

Why it matters

Google's course says a good document begins by defining its scope, and a better one also defines its non-scope: topics the reader might expect but that the document will not cover. It also suggests a blunt test: imagine your peers might only read the first paragraph.

So the opening of any document should answer:

  • What is this? One sentence.
  • Who is it for? Roles and prerequisites.
  • What is not covered? And where to find it.
  • What is the main point or ask?
text
This page explains how to rotate the payments API keys.
For: on-call engineers with production access.
Not covered: creating new API clients (see "Onboarding a client").
Rotation takes about 15 minutes and needs no downtime.

Do

  • Put the main point in the first paragraph
  • Link to where out-of-scope topics live

Avoid

  • Building up slowly to the point at the end