97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# Documentation style guide
|
||
|
||
This repository aims for a NetBox-like style: clear, technical, and written for working engineers.
|
||
|
||
## Voice and tone
|
||
|
||
- **Direct and technical.** Prefer short sentences and specific nouns.
|
||
- **Narrative flow.** Describe how the system behaves, not how the doc was produced.
|
||
- **Calm, professional tone.** Avoid hype.
|
||
- **Assume competence, not context.** Define repo-specific terms once, then reuse them.
|
||
|
||
## Page structure (default)
|
||
|
||
Use a consistent, scan-friendly layout.
|
||
|
||
1. **Title**
|
||
2. **1–3 sentence intro**
|
||
- What this page covers and who it’s for.
|
||
3. **Deep dives / Related docs** (optional but common)
|
||
- Links to more detailed pages.
|
||
4. **Main content**
|
||
- Prefer sections that match user intent: “Quickstart”, “How it works”, “Configuration”, “Common workflows”, “Troubleshooting”.
|
||
5. **Next steps** (optional)
|
||
- Where to go next.
|
||
|
||
## Headings and conventions
|
||
|
||
- Prefer **verb-led** headings when describing procedures: “Run migrations”, “Regenerate the client”.
|
||
- Prefer **intent-led** headings when describing concepts: “How requests flow”, “Auth model”.
|
||
- Use numbered steps when order matters.
|
||
- Keep headings short; avoid long parentheticals.
|
||
|
||
## Cross-linking
|
||
|
||
- Treat the numbered IA pages in `docs/` as **entrypoints**.
|
||
- Link to deep dives instead of duplicating content.
|
||
- Use readable link text:
|
||
- Good: “Deployment guide” → `docs/deployment/README.md`
|
||
- Avoid: ``docs/deployment/README.md``
|
||
|
||
## Link formatting rules
|
||
|
||
- Use markdown links: `[Deployment guide](deployment/README.md)`.
|
||
- Use relative paths that work in GitHub and typical markdown renderers.
|
||
- Keep code formatting for:
|
||
- commands (`make check`)
|
||
- environment variables (`NEXT_PUBLIC_API_URL`)
|
||
- literal file paths when you mean “this exact file on disk” (not as a navigational link)
|
||
|
||
## Avoided phrases (and what to use instead)
|
||
|
||
Avoid doc-meta language:
|
||
|
||
- Avoid: “evidence basis”, “evidence anchors”, “this page is intentionally…”
|
||
- Prefer:
|
||
- “Source of truth: …” (only when it matters)
|
||
- “See also: …”
|
||
- Just link the file or section.
|
||
|
||
Avoid hedging:
|
||
|
||
- Avoid: “likely”, “probably”, “should” (unless it’s a policy decision)
|
||
- Prefer: state what the code does, and point to the file.
|
||
|
||
## Preferred patterns
|
||
|
||
- **Start here** blocks for role-based entry.
|
||
- **Common workflows** sections with copy/paste commands.
|
||
- **Troubleshooting** sections with symptoms → checks → fixes.
|
||
- **Footguns** called out explicitly when they can cause outages or confusing behavior.
|
||
|
||
## Example rewrites
|
||
|
||
### Example 1: remove doc-meta “evidence” language
|
||
|
||
Before:
|
||
> Evidence basis: consolidated from repo root `README.md`, `.github/workflows/ci.yml`, `Makefile`.
|
||
|
||
After:
|
||
> This page describes the development workflow that matches CI: setup, checks, and common local loops.
|
||
|
||
### Example 2: prefer readable links over code-formatted paths
|
||
|
||
Before:
|
||
- See `docs/deployment/README.md` for deployment.
|
||
|
||
After:
|
||
- See the [Deployment guide](deployment/README.md).
|
||
|
||
### Example 3: replace “first pass” filler with a clear scope boundary
|
||
|
||
Before:
|
||
- Non-goals (first pass)
|
||
|
||
After:
|
||
- Out of scope
|