Content guidelines

Write for a specific reader need. Prefer a short canonical page that can be maintained over a comprehensive document that mixes unrelated purposes.

Keep content durable

• Preserve conclusions, decisions, and reusable evidence rather than raw discussion or progress updates.
• Update the existing canonical page instead of publishing overlapping guidance.
• Separate confirmed facts from interpretations, proposals, and open questions.
• Remove obsolete content when its replacement is added.

Be clear and concise

• Start with the conclusion or the reader’s goal.
• Use descriptive headings, short paragraphs, and direct language.
• Explain necessary context, but omit process history that does not change how the content should be understood or used.
• Prefer Markdown. Use MDX only when a component materially improves comprehension.

Be trustworthy

• Verify factual claims against current, authoritative sources.
• Link to primary sources when readers may need to recheck a changing fact.
• State uncertainty and unresolved questions explicitly.
• Never include secrets, credentials, personal data, private tokens, or sensitive internal values.
• Do not invent owners, dates, metrics, commands, URLs, or implementation status.

Make pages accessible

• Add meaningful alternative text to images.
• Explain the important conclusion of a diagram in prose.
• Use descriptive link text instead of raw URLs or “click here.”
• Keep examples minimal, safe to copy, and free of sensitive values.