# Docs > Documentation rules - Markdown, README, JSDoc, TypeDoc, changelogs, technical writing conventions - Skill: `14bryanespinoza/docs` (Agent Skill) - Install (CLI): `npx skillmds@latest add 14bryanespinoza/docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/14bryanespinoza/docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: 14BryanEspinoza (https://skillmd.com/u/14bryanespinoza) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/14bryanespinoza/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 ```markdown # 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 ```markdown - Unordered item - Another item - Nested item (2 spaces) - Another nested 1. Ordered step one 2. Ordered step two 1. Sub-step ``` ### Tables ```markdown | Header 1 | Header 2 | Header 3 | | -------- | :------: | -------: | | Left | Center | Right | | Data | Align | Works | ``` - **Header row required** — separator row with `---` - **Alignment** — `:` left, `:---:` center, `---:` right ### Code blocks ```ts // Fenced block with language function greet(name: string): string { return `Hello, ${name}!`; } ``` ```bash # Shell commands pnpm install ``` ```text # Plain output (no highlighting) Error: connection refused ``` - **Always specify language** — enables highlighting - **`bash` for shell**, `text` for plain output ### Links and images ```markdown [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) ```ts /** * 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 { ... } ``` ### Essential tags only | Tag | Use | | ------------- | -------------------------------- | | `@param` | Parameters with description | | `@returns` | Return value description | | `@throws` | Thrown errors | | `@example` | Minimal usage example | | `@deprecated` | Mark deprecated with replacement | | `@see` | Link to related symbol | ### TypeDoc config ```json // 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 ```markdown # 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 ````markdown # Project Name One-line description. What problem does it solve? ## Quick Start ```bash pnpm install pnpm dev ``` ```` ## Features - Feature 1 - Feature 2 ## Documentation - [Architecture](./docs/architecture.md) - [API Reference](./docs/api.md) - [Contributing](./CONTRIBUTING.md) ## License MIT ### Architecture Decision Records (ADR) ```markdown # 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 ```mermaid %% 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 ````markdown # 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 ``` ```` ## States - Default - Hover - Focus (visible ring) - Disabled - Loading > **Full component design rules**: see `component-design` skill. --- ## 8. Tools | Tool | Purpose | Config | | ------------------------------- | ---------------- | -------------------- | | **TypeDoc** | API docs from TS | `typedoc.json` | | **typedoc-plugin-markdown** | Markdown output | — | | **markdownlint** | Lint Markdown | `.markdownlint.json` | | **VitePress / Astro Starlight** | Doc site | — | ### markdownlint config ```json // .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 | Rule | Example | | ----------------------- | ------------------------------------------------------ | | **Active voice** | "The function returns..." not "A value is returned..." | | **Present tense** | "Run `pnpm install`" not "You will run..." | | **Second person** | "Configure your..." not "The user configures..." | | **Imperative** | "Add the dependency" not "You should add..." | | **Specific over vague** | "Set `timeout: 5000`" not "Set a reasonable timeout" | | **Define acronyms** | "Core Web Vitals (CWV)" on first use | ### 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 ```markdown ## 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](../html/SKILL.md) > **Note:** For CSS conventions, see [CSS](../css/SKILL.md) > **Note:** For JavaScript conventions, see [JavaScript](../javascript/SKILL.md) > **Note:** For TypeScript rules, see [TypeScript](../typescript/SKILL.md) > **Note:** For React component design, see > [Component Design](../component-design/SKILL.md) > **Note:** For Git/PR conventions, see [Git](../git/SKILL.md) > **Note:** For package manager conventions, see > [Package Manager](../package-manager/SKILL.md) --- Last updated: 2026-08