# Documentation Standards — CVE Dashboard These standards are reverse-engineered from the existing README.md and should be treated as the canonical style guide for all documentation in this repository. When updating docs, match these conventions exactly — consistency matters more than any individual stylistic preference. --- ## Language and Style - Write in **present tense, active voice**. "The sync fetches findings" — not "Findings will be fetched by the sync." - Do not use marketing language. No "powerful", "seamless", "robust", "cutting-edge", "unleash". Describe what the thing does, not how great it is. - No emoji anywhere in documentation. None. - Prefer precise technical vocabulary over casual phrasing. "Session tokens are stored in `httpOnly` cookies" — not "we keep the login thing in a secure cookie." - **Spelling:** match whatever spelling variant already appears in the surrounding prose. Do not rewrite existing words to switch between US and British English — consistency within a section matters more than which variant is used. --- ## Punctuation and Formatting - **Em-dashes (—)** for mid-sentence clarifications or appositives, surrounded by spaces: `sync requires Admin or Standard_User group — the sync then fetches findings`. - **En-dashes (–)** for numeric ranges: `8.5–9.9 VRR`, `20 attempts per 15-minute window`. - Use **inline backticks** for: file paths, environment variables, CLI flags, function names, field names, HTTP status codes, and any literal value the reader should type or recognise verbatim. - Use **bold** (`**text**`) for UI element names (button labels, tab names, form fields) and for label-style emphasis at the start of a sub-point. - Avoid italics except for rare genuine emphasis. Do not use italics decoratively. --- ## Heading Hierarchy Use a strict three-tier hierarchy per document: ``` # Document Title (one per file, matches repo/feature name) ## Top-Level Section (Overview, Features, Architecture, etc.) ### Subsection (a named feature, page, or concept) **Sub-subsection label** (bold paragraph labels — NOT an #### heading) ``` - Do **not** use `####` or deeper headings. If you need a fourth level, it should be a bold inline label followed by content, matching the existing README pattern. - Separate top-level `##` sections with a horizontal rule (`---`) on its own line, with blank lines above and below. - Do not place horizontal rules between `###` subsections unless visually necessary. --- ## Table of Contents - Any document over ~200 lines should open with a Table of Contents using markdown anchor links. - Nest TOC entries to match heading depth (`##` entries flush-left, `###` entries indented two spaces). - Anchor slugs: lowercase, spaces become hyphens, em-dashes become `--` (two hyphens). Example: `## Home — CVE Management` becomes `#home--cve-management`. --- ## Tables Use tables for any reference material with two or more parallel attributes. This includes: - Permission matrices (group → capabilities) - Tech stack listings (layer → technology) - Column descriptions (column → meaning) - Environment variable references (name → purpose → default) - Route references (method + path → description → auth requirement) Table format: ```markdown | Column | Description | |---|---| | `field_name` | What it does | ``` - Always use `---` separators (not `:---:` centred alignment) unless centring is specifically warranted. - Keep cell content on a single line. If a value is long, prefer prose above or below the table. - Use inline backticks for literal values inside cells. --- ## Code Blocks - **Always include a language tag** on fenced code blocks: ` ```bash `, ` ```javascript `, ` ```json `, ` ```python `, ` ```sql `. Bare ` ``` ` is not acceptable. - Shell commands use `bash` — even for single-line commands. - Place code blocks on their own line, with blank lines before and after. - Inside code blocks, do not use markdown formatting (no bold, no italics). Treat them as literal terminal/file content. - Prefer showing the actual command over describing what to do. "Run `node setup.js` from `backend/`" with a code block — not "initialize the database." --- ## Callouts and Warnings - Use a blockquote (`>`) for callouts, notes, and warnings. Do not use GitHub-flavoured admonition syntax (`> [!NOTE]`), Docusaurus admonitions, or custom HTML. - Keep callouts to one or two sentences. If longer, promote to prose. - Example: `> IVANTI_API_KEY must be set in backend/.env for sync to work.` Bold prefixes for emphasis are acceptable inside a blockquote: `> **Warning:** This deletes all audit records older than 90 days.` --- ## Feature Documentation Pattern When documenting a feature or page, follow this structure: 1. **One-sentence summary** of what the feature is and who uses it. 2. **Capability bullets** — what a user can do, grouped by role if access-controlled. 3. **Workflow or interaction details** — how the feature is used in practice (inline editing behaviour, filter semantics, persistence rules). 4. **Integration notes** — what external systems it touches, what credentials it needs, what it caches. 5. **Edge cases and restrictions** — delete rules, rate limits, role requirements. Bold paragraph labels (`**Inline editing:**`, `**CVE Tooltips:**`, `**Filtering:**`) are the preferred pattern for calling out sub-behaviours within a feature section. --- ## Troubleshooting Entries Every troubleshooting entry uses the **Symptom → Cause → Fix** triad: ```markdown ### Short description of the problem **Symptom:** What the user sees or experiences. Be specific about error messages, console output, and observed behaviour. **Cause:** The underlying reason, explained in one or two sentences. Include the technical mechanism (cookie flag, rate limiter, missing migration) — not just "it's broken." **Fix:** Either: 1. Concrete action with a command or config change, **or** 2. Alternative action. ``` - Short entries (fix is one command) may collapse Cause into Fix, but Symptom must always appear explicitly. - Use **Fix:** as the label, not "Solution" or "Resolution." --- ## CHANGELOG This project does not currently maintain a `CHANGELOG.md`. The doc-updater agent should **not** create one unless explicitly instructed. When a change ships, rely instead on: - **Git commit messages** as the primary change history. Write them as complete sentences describing user-observable behaviour, not implementation detail. "Add inline editing to CVE reporting table" — not "fix table.jsx." - **README updates** as the user-facing record of what the app does now. The README is the source of truth for current behaviour; git log is the source of truth for when and why it changed. If a `CHANGELOG.md` is introduced later, this section should be rewritten to declare the chosen format. Until then, the agent should leave changelog concerns out of scope. --- ## Migration Documentation When a feature requires a new database migration: 1. Add the migration filename to the README's **Migrations** section in the order it must be run. 2. If the migration is required for an existing deployment (not just fresh installs), add a Troubleshooting entry using the Symptom → Cause → Fix pattern for the error users will see if they skip it. 3. Note any data-transforming migrations explicitly — users need to know whether the migration is additive (safe to re-run) or transformative (destructive if re-run). --- ## API Reference Documentation - Document routes as: `METHOD /path/with/:params` - Group routes by resource or page (CVE routes, Ivanti routes, Audit routes). - For each route, specify: purpose, required group, request body or query params, response shape summary. Keep it to 2–4 lines per route. - Do not duplicate route implementation details. Link to the source file if deeper reference is needed. - When a route enforces group-based authorisation, state the required group explicitly — do not imply it from context. --- ## What to Update When a Feature Ships A new feature or meaningful change to existing behaviour should touch: 1. **README.md — Features section:** add or update the relevant `###` subsection, matching the Feature Documentation Pattern above. 2. **README.md — Table of Contents:** if a new feature added a new heading, update the TOC to match. 3. **README.md — Configuration:** if new env vars were introduced, add them to the Configuration table. 4. **README.md — API Reference:** if new routes were added, document them under the appropriate resource group. 5. **README.md — Database Schema:** if tables or columns changed, update the schema section. 6. **README.md — Migrations:** if a new migration was added, append it to the ordered list. 7. **docs/**: if the feature has its own standalone guide (setup guide, integration guide), create or update the relevant file in `docs/`. If a change does not alter user-observable behaviour, configuration, data model, or API surface, it does not require doc changes. Internal refactors, test additions, and dependency bumps are exempt unless they change how the app is run or deployed. --- ## What NOT to Change The doc-updater agent and human contributors alike should **leave alone**: - Tone, voice, and spelling conventions of existing prose. Match, do not rewrite. - Section ordering in the README — the current order is deliberate and reader-tested. - Heading wording, unless the underlying feature has genuinely been renamed. - Examples and command snippets that still work, even if they could be "more elegant." - The overall shape of the Troubleshooting section — append new entries, do not reorganise existing ones. Documentation churn is a cost. Only change what the code change requires.