documentation-standards

name	documentation-standards
description	Clear technical documentation — JSDoc, Mermaid, READMEs, ADRs, C4 diagrams, ISMS policy citations
license	MIT

Documentation Standards Skill

Context

Applies when writing READMEs, documenting APIs/functions/classes, creating architecture docs, adding JSDoc, drawing diagrams, writing ADRs, documenting security policies, or writing user guides.

Aligned with the architecture-documentation expectations in Secure Development Policy §Architecture Documentation Matrix.

Rules

1. ISMS References — security-relevant docs cite the applicable Hack23 policy
2. JSDoc for Public APIs — every export gets @param, @returns, @example (and @throws where relevant)
3. Include TypeScript types in JSDoc context (types live in code; JSDoc describes behavior)
4. Working examples — every snippet compiles and matches current behavior
5. Document exceptions — @throws for every thrown error type
6. Mermaid diagrams — never screenshots; always include source
7. Keep READMEs current — updates ship in the same PR as code changes
8. Link authoritative external docs — React, Three.js, vitest, ISO/NIST/CIS
9. Show anti-patterns — ❌ examples beside ✅ for high-impact APIs
10. Accessible markdown — semantic headings, descriptive links, alt text for images
11. Heading hierarchy — H1 → H2 → H3, never skip levels
12. Specify code-block languages ( ```typescript, ```bash, ```mermaid)
13. ADRs for lasting decisions — numbered, dated, status tracked (Proposed / Accepted / Deprecated / Superseded)
14. No PII in examples — synthetic data only

Documentation Portfolio (Hack23 standard)

File	When	Purpose
README.md	Always	Overview, badges, quick start, classification
SECURITY.md	Always	Vulnerability reporting
SECURITY_HEADERS.md	Web	Runtime headers
docs/ISMS_POLICY_MAPPING.md	Always	Feature → policy
docs/ARCHITECTURE.md	Non-trivial	C4 Context / Container / Component
docs/DATA_MODEL.md	Stateful	Data structures
docs/FLOWCHART.md	Processes	Business flows
docs/STATEDIAGRAM.md	Stateful features	State transitions
docs/FUTURE_*.md	Roadmap	Future-state counterparts

Examples

✅ JSDoc for a game function

/**
 * Calculates the active target count for a given game level.
 *
 * ISMS: Secure Development Policy §Phase 2 — Secure Coding
 *
 * @param level - Current game level (≥ 1)
 * @returns Number of active targets (1–3) for the level
 * @throws {RangeError} When `level` is not a finite integer ≥ 1
 *
 * @example
 * ```typescript
 * getTargetCountForLevel(1); // 1
 * getTargetCountForLevel(5); // 2
 * getTargetCountForLevel(8); // 3
 * ```
 */
export function getTargetCountForLevel(level: number): number {
  if (!Number.isFinite(level) || level < 1) {
    throw new RangeError('level must be a finite integer ≥ 1');
  }
  if (level <= 3) return 1;
  if (level <= 6) return 2;
  return 3;
}

✅ C4 Context diagram (Mermaid)

```mermaid
graph TB
  Player((Player)) -->|Plays| App[Target Shooter SPA]
  App -->|Loads assets| CDN[(Bundled static assets)]
  App -->|Audio| Howler[Howler.js]
  App -->|Renders| Three[Three.js / WebGL]
```

✅ ADR skeleton

# ADR 0001 — Adopt Vitest for Unit Testing
- **Status:** Accepted (2025-11-10)
- **Context:** Need fast, ESM-native test runner compatible with Vite.
- **Decision:** Use Vitest with jsdom.
- **Consequences:** Faster feedback; minor migration from Jest APIs.
- **ISMS:** Secure Development Policy §Phase 3 — Security Testing

❌ Anti-Patterns

// BAD: exported function with no JSDoc
export function calc(x: number) { return x * 2; }

// BAD: @example that contradicts behavior
/** @example calc("2"); // 4 */
export function calc(v: number): number { return v * 2; }

// BAD: screenshot-only diagram
// (not maintainable, not accessible, not diffable)

Validation Checklist

• Every public export has JSDoc with a working @example
• Diagrams are Mermaid source (not images)
• All internal + external links resolve
• Heading hierarchy is correct (no skipped levels)
• Code blocks specify a language
• Security docs cite the applicable ISMS policy
• Anti-patterns shown for non-trivial APIs
• No PII or real-user data in examples