Writing

Start with what the reader will do. Put the command or action next to its result.

Structure a task

1. Name the task in the title.
2. State prerequisites that affect whether it works.
3. Show the smallest working example.
4. Explain how to verify the result.
5. Add troubleshooting for failures readers can encounter.

Keep the useful detail

Remove introductions that repeat the title, slogans, and labels that explain the layout. Keep permissions, version constraints, costs, security requirements and recovery instructions.

Code and examples

Use realistic placeholder values. Label the language. Never use a live API key or a project ID that sends test traffic to somebody else's account.

Use code blocks for commands and steps for a sequence of actions. Use a callout when a detail changes a decision, not to decorate a paragraph.

Readers and agents

Put the answer in the rendered page. Use descriptive links, semantic headings and text alternatives for images. Keep important instructions outside tabs when every reader needs them.

A theme improves presentation. It does not make incomplete or outdated instructions reliable.