Style guide
Voice, structure and word choices that make technical content easy to read.
1 min read
A style guide removes small decisions so writers can focus on the reader. Ours fits on one page.
Voice#
Write the way a helpful senior colleague would explain it: direct, specific, calm.
- Address the reader as you.
- Use the active voice. Say who does what.
- Use the present tense: "The API returns a token", not "will return".
- Prefer short sentences. Aim for an average under 20 words.
| Instead of | Write |
|---|---|
| The token is generated by the server. | The server generates the token. |
| Simply click the Save button. | Click Save. |
| In order to authenticate, you will need to… | To authenticate, you need… |
| Utilize the endpoint to leverage data. | Use the endpoint to get data. |
Words to cut#
Words like simply, just, easily and obviously are quietly hostile. If the reader is stuck, the task wasn't simple. Delete them.
Structure#
Headings#
- Sentence case: "Verify a webhook signature".
- Start task headings with a verb.
- Never skip a level: H2 then H3, never H2 then H4.
Procedures#
Use a numbered list. One action per step. Put the expected result on its own line after the step.
Code samples#
- Every sample must run as written.
- Show the language on every fence so it highlights correctly.
- Use realistic values, never
fooandbar. - Keep secrets out. Use obvious placeholders such as
YOUR_API_KEY.
curl https://api.example.com/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY"Callouts#
| Type | Use it for |
|---|---|
| Note | Context that helps but isn't required |
| Tip | A faster or safer way to do the task |
| Warning | Something that can cause data loss or confusion |
Try the Readability Lab to check a paragraph against these rules.
Was this page helpful?