Docs

Documentation — Rules and Conventions

1. Philosophy

1. Docs as code — Versioned, reviewed, tested alongside code. Lives in repo.
2. Audience-first — Write for the reader (new contributor, user, future you), not for yourself.
3. Single source of truth — Generate from source (TypeDoc, OpenAPI) when possible. Avoid duplication.
4. Living documentation — Update in same PR as code change. Stale docs are worse than no docs.
5. Minimal viable docs — Document decisions, not obvious mechanics. Link to authoritative sources.

2. Markdown — Essential Rules

Headings

# H1: Page title (one per file)

## H2: Major section

### H3: Subsection

#### H4: Detail (avoid deeper)

• One H1 per file — matches page title
• Sequential — no skipping levels (H1 → H3 invalid)
• Sentence case — "## Getting started" not "## Getting Started"

Lists

- Unordered item
- Another item
  - Nested item (2 spaces)
  - Another nested

1. Ordered step one
2. Ordered step two
   1. Sub-step

Tables

| Header 1 | Header 2 | Header 3 |
| -------- | :------: | -------: |
| Left     |  Center  |    Right |
| Data     |  Align   |    Works |

• Header row required — separator row with ---
• Alignment — : left, :---: center, ---: right

Code blocks

// Fenced block with language
function greet(name: string): string {
  return `Hello, ${name}!`;
}

# Shell commands
pnpm install

# Plain output (no highlighting)
Error: connection refused

• Always specify language — enables highlighting
• bash for shell, text for plain output

Links and images

[Link text](https://example.com)
[Relative link](../other-file.md)
[Reference link][ref]

[ref]: https://example.com "Optional title"

![Alt text](/path/to/image.png "Optional title")

• Relative links for repo files — survives moves
• Descriptive link text — not "click here"

3. API Documentation (JSDoc / TypeDoc)

JSDoc patterns (TypeScript)

/**
 * Fetches user by ID from the API.
 * @param id - User UUID
 * @returns User object or null if not found
 * @throws {ApiError} When request fails
 * @example
 * const user = await fetchUser("123e4567-e89b-12d3-a456-426614174000")
 */
async function fetchUser(id: string): Promise<User | null> { ... }

Essential tags only

TypeDoc config

// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "theme": "default",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "excludePrivate": true,
  "excludeProtected": true
}

Full TypeScript/JSDoc rules: see typescript skill.

4. Changelog (Keep a Changelog)

Format

# Changelog

All notable changes documented here. Format based on [Keep a Changelog](https://keepachangelog.com/).

## [Unreleased]

### Added

- Feature X (#123)

### Changed

- Behavior Y (#456)

### Fixed

- Bug Z (#789)

## [1.2.0] - 2026-08-15

### Added

- New API endpoint for user search

### Changed

- Updated dependency versions

### Deprecated

- Old `fetchUser` — use `fetchUserById`

## [1.1.0] - 2026-07-01

...

Rules

• Sections: Added, Changed, Deprecated, Removed, Fixed, Security
• Links to PRs/issues — (#123) format
• Date — ISO format (YYYY-MM-DD)
• Unreleased at top — moves to version on release
• One file — CHANGELOG.md at repo root

5. Technical Documentation

README structure

# Project Name

One-line description. What problem does it solve?

## Quick Start

```bash
pnpm install
pnpm dev
```

Features

• Feature 1
• Feature 2

Documentation

• Architecture
• API Reference
• Contributing

License

MIT

Architecture Decision Records (ADR)

# ADR 001: Use Astro for frontend

## Status

Accepted

## Context

Need fast, content-first framework with island hydration.

## Decision

Adopt Astro 4.x with React islands.

## Consequences

- Pros: Zero-JS default, great DX, content collections
- Cons: Learning curve for team

• One ADR per decision — immutable once accepted
• Numbered sequentially — 001, 002, ...
• Location: docs/adr/NNN-title.md

6. Mermaid Diagrams

Essential types only

%% Architecture
graph TD
  A[Client] --> B[API Gateway]
  B --> C[Auth Service]
  B --> D[User Service]

%% Sequence
sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  U->>F: Login
  F->>B: POST /auth
  B-->>F: JWT
  F-->>U: Session

%% State
stateDiagram-v2
  [*] --> Loading
  Loading --> Success: data fetched
  Loading --> Error: fetch failed

Rules Mermaid Diagrams

• Types: graph, sequenceDiagram, stateDiagram-v2, classDiagram
• Embed in Markdown — render via mermaid in GitHub/GitLab/VitePress
• Keep simple — complex diagrams belong in separate .mmd files

7. Component Documentation

Minimal component doc

# Button

Primary action component. Variants: primary, secondary, ghost.

## Props

| Name       | Type                                  | Default     | Description          |
| ---------- | ------------------------------------- | ----------- | -------------------- |
| `variant`  | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Visual style         |
| `disabled` | `boolean`                             | `false`     | Disables interaction |
| `onClick`  | `() => void`                          | —           | Click handler        |

## Usage

```tsx
<Button variant="secondary"
  Click me
</Button>
```

States

• Default
• Hover
• Focus (visible ring)
• Disabled
• Loading

Full component design rules: see component-design skill.

8. Tools

markdownlint config

// .markdownlint.json
{
  "default": true,
  "MD013": { "line_length": 80, "code_blocks": false, "tables": false },
  "MD033": false,
  "MD041": false
}

9. Documentation in PRs

PR template owned by git skill — this skill defines doc-specific checks.

Required updates per PR

• README updated if user-facing change
• CHANGELOG entry added (Unreleased section)
• API docs regenerated if public API changed (pnpm docs:api)
• ADR added for architectural decisions
• Component docs updated if props/behavior changed

10. Writing Style

Essential rules

Formatting

• Code references in backticks: functionName, ClassName, propName
• File paths in backticks: src/utils.ts
• Commands in bash blocks (not inline)
• One sentence per line — easier diffs, reviews

11. Configuration Documentation

Document config schemas

## Configuration

### `vite.config.ts`

| Option         | Type     | Default    | Description     |
| -------------- | -------- | ---------- | --------------- |
| `server.port`  | `number` | `3000`     | Dev server port |
| `build.target` | `string` | `'es2022'` | Output target   |

### Environment variables

| Variable       | Required | Default         | Description          |
| -------------- | -------- | --------------- | -------------------- |
| `VITE_API_URL` | Yes      | —               | Backend API base URL |
| `NODE_ENV`     | No       | `'development'` | Runtime environment  |

Full config conventions: see package-manager, vite, astro skills.

12. Methodology

Before using ANY documentation pattern/tool not documented in this skill:

1. MCP Context7 (priority): context7_resolve-library-id + context7_query-docs for TypeDoc, VitePress, etc.
2. Official docs: typedoc.org, vitepress.dev, markdownlint.org — verify current options.
3. Project config: typedoc.json, .markdownlint.json, CHANGELOG.md — verify against actual setup.
4. HARD RULE: If not in this skill AND cannot be verified against 2 authoritative sources → DO NOT USE IT. Document as assumption or risk in report to orchestrator.

13. Prohibitions

• ❌ Do not document obvious code (getters, setters, simple props)
• ❌ Do not duplicate TypeScript types in JSDoc — TypeDoc reads TS directly
• ❌ Do not commit generated API docs — build in CI, deploy to site
• ❌ Do not write "TODO" in docs — create issue instead
• ❌ Do not use H5/H6 headings — restructure instead
• ❌ Do not skip CHANGELOG entry for user-facing changes
• ❌ Do not write docs in PR description — put in repo files
• ❌ Do not use ambiguous links ("here", "this") — descriptive text

14. References

Note: For HTML conventions, see HTML Note: For CSS conventions, see CSS Note: For JavaScript conventions, see JavaScript Note: For TypeScript rules, see TypeScript Note: For React component design, see Component Design Note: For Git/PR conventions, see Git Note: For package manager conventions, see Package Manager

Last updated: 2026-08