Structure and Clarity

Lead with the important stuff:

Make headings do the work:

Instructions and Examples

Tell people what to do:

Answer unasked questions:

Code vs. UI elements:

Use familiar terms from tools people already know:

Avoid these patterns:

Who is this for? Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
What do they need? Get them to the answer fast. Nobody wants to be in docs longer than necessary.
What did you struggle with? Those common questions you had when learning? Answer them (without literally including the question).

Draft:

Write out the steps/explanation as you'd tell a colleague
Lead with what to do, then explain why
Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"

Edit:

Polish:

Format:

Run prettier on the file after making edits: yarn prettier --write <file-path>
This ensures consistent formatting across all documentation

Instructions:

Run:
\`\`\`
command-to-run
\`\`\`

Then:
\`\`\`
next-command
\`\`\`

This ensures you're getting the latest changes.

Not: "(remember to run X before Y...)" buried in a paragraph.

Headings:

Links: