Documentation Style Guide

TankSafe documentation should be approachable, accurate, and actionable. This style guide defines the standards for writing, structuring, and maintaining content across the site.

Guiding principles

1. Task-first: Lead with the outcome readers care about, then provide necessary context.
2. Accurate and current: Cross-reference source code, Supabase policies, and product screenshots before publishing.
3. Inclusive language: Avoid jargon where plain language works; explain industry terms in the Glossary.
4. Scannable layout: Keep sections short, use descriptive headings, bullets, tables, and admonitions for emphasis.
5. Source controlled: Treat documentation changes like code—branch, PR, review, merge.

Page anatomy

Every page should follow this blueprint where practical:

1. Frontmatter metadata
   • Required: title, slug, sidebar_position
   • Optional: tags, description, keywords
2. Executive summary
   • A 1–2 sentence overview of the page's purpose.
3. Prerequisites
   • List tools, roles, permissions, feature flags.
4. Execution steps
   • Numbered flow for task guides or subheadings for conceptual docs.
   • Embed callouts for warnings/tips using Docusaurus admonitions.
   • Reserve explicit placeholders for visuals:
     • <!-- TODO: Add screenshot of [screen/context] -->
5. Validation & next steps
   • How to confirm success, where to go next, related links.
6. Support
   • Point to escalation channel or runbook.

Tone & voice

• Write in second person ("You") for task guides; use neutral third person for architecture references.
• Prefer present tense.
• Keep sentences under 25 words when possible.
• Avoid metaphor, idiom, or humour that may confuse non-native speakers.

Formatting standards

Element	Guidance
Headings	Sentence case (## Configure email notifications)
Code	Use fenced blocks with language hint; prefer snippets from repository files
Tables	Add headers, keep column count ≤ 4 for readability
Links	Relative links inside docs, absolute for external references
Screenshots	Insert as MDX image when available; always include alt text
Admonitions	:::tip, :::caution, :::danger, etc.

Screenshot workflow

1. Capture: Use a 1440px wide browser window in light theme unless the feature mandates dark mode.
2. Annotate: Highlight with brand-colour rectangles if needed; avoid large text overlays.
3. Optimise: Export as WebP under static/img/docs/... with descriptive names.
4. Placeholder: Add a TODO comment until the screenshot is committed.
   • Example: <!-- TODO: Add screenshot of Admin > Users table with MFA badges -->
5. Update: Replace comment with <img alt="..." src="/img/docs/..." /> once asset is available.

Tooling & linting

• Run npm run lint:md before submitting a PR (add script if missing).
• Use Prettier with the repository configuration (see package.json).
• Validate links locally with npx docusaurus swizzle -- --help (or future link-check script).
• Enable the VS Code "Markdown All in One" and "Vale" extensions for consistent grammar.

Review checklist

• Frontmatter present and accurate
• Headings follow hierarchy (no skipped levels)
• Screenshots or TODO comments in place
• Links resolve
• Steps tested against latest build (development branch)
• Stakeholder SME reviewed technical accuracy

Documentation contributions process

1. Create an issue or note in the docs backlog describing the change.
2. Branch from development, naming the branch docs/<topic>-<initials>.
3. Make changes, running lint and build locally.
4. Submit a PR with context, screenshots, and checklist confirmations.
5. Request review from the docs owner and relevant SMEs.
6. Merge once approvals are complete and the build passes.
7. Monitor analytics/feedback after publish to gauge adoption.