GitHub docs

Help developers complete a product workflow with accurate, approachable guidance.

Establish the contract

• Preserve commands, UI labels, permissions, plan or product availability, code, versions, and security consequences.
• Do not claim a feature exists for a plan, host, or version without evidence.
• Distinguish a supported workflow from a workaround or community convention.
• Surface missing facts as review questions.

Design the page

1. Name the reader's goal in the title and opening.
2. State prerequisites, permissions, supported environments, and risks before the reader reaches a dependent action.
3. Give only enough concept to make the action understandable and safe.
4. Present the shortest supported path first. Place alternatives in separate sections.
5. Close the loop with verification, troubleshooting, or a useful next step.

Write for developers

• Address the reader as you and keep the tone calm and collaborative.
• Use active voice and concrete verbs. Name the component that performs an automatic action.
• Define product-specific terms on first use and keep terminology stable.
• Put the most important qualifier near the claim it limits.
• Explain why a step matters when the reason affects security, data, or the choice between alternatives.
• Use inclusive language and examples that do not assume geography, identity, or a single development environment.
• Separate normative instructions from optional suggestions.

Write procedures

• Begin steps with imperative verbs and use one main action per step.
• State the location before the control when the reader must navigate to it.
• Keep commands copyable. Explain substitutions and show the expected output only when it helps verify success.
• Put warnings directly before irreversible or security-sensitive actions.
• Offer recovery paths that state what data or configuration may change.

Make the page scannable

• Use sentence case and front-load meaningful words in headings.
• Use descriptive link text instead of generic destinations.
• Use numbered lists for sequences, bullets for options, and tables for repeated comparisons with the same fields.
• Use backticks for code and literal technical elements. Use bold for visible UI labels.
• Keep notes exceptional. Move essential information into the main flow.

Avoid

• assuming a step is obvious, trivial, or familiar
• long scene-setting introductions and repeated summaries
• vague references to this, that, or it
• blaming the reader in warnings and error explanations
• promises that a workflow is secure, fast, or reliable without scope and evidence
• examples with real personal data, tokens, organization names, or secrets

Final pass

Walk the page as the intended reader. Verify that every prerequisite arrives in time, every control and command is identifiable, branching is explicit, and the reader can tell whether the workflow succeeded.

Read references/provenance.md only for source, attribution, licensing, or maintenance questions.