# Docs Codebase

> Technical writing for READMEs, ADRs, API docs, and changelogs. Use when revising or consolidating a repo documentation folder. Use when this capability is needed.

- Skill: `tomevault-io/docs-codebase` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/docs-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-codebase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/docs-codebase

---


# Technical Documentation

Execution-ready patterns for clear, maintainable technical documentation.

**Modern best practices (January 2026)**: docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.

## Quick Reference

| Documentation Type | Template | When to Use |
|-------------------|----------|-------------|
| **Project README** | [readme-template.md](assets/project-management/readme-template.md) | New project, onboarding |
| **Architecture Decision** | [adr-template.md](assets/architecture/adr-template.md) | Technical decisions |
| **API Reference** | [api-docs-template.md](assets/api-reference/api-docs-template.md) | REST/GraphQL APIs |
| **Changelog** | [changelog-template.md](assets/project-management/changelog-template.md) | Version history |
| **Contributing Guide** | [contributing-template.md](assets/project-management/contributing-template.md) | Open source, teams |

## Workflow

1. Identify the documentation type and audience.
2. Find existing patterns in the repo; follow local conventions.
3. Start from the closest template in `assets/` and adapt.
4. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
5. Run documentation QA (links, formatting, spelling, examples) before merging.

### Docs Folder / LLM-Generated Revamp Mode (Any Repo)

Use this mode when a repo's `docs/` folder contains substantial research notes for LLMs and implementation docs generated by LLMs.

1. Build an inventory and classify each file by doc type (`Tutorial`, `How-to`, `Reference`, `Explanation`).
2. Mark lifecycle metadata for non-canonical files:

```yaml
status: draft | canonical | integrated | superseded
owner: @username
last_verified: 2026-02-24
integrates_into: docs/path/to/canonical-doc.md
delete_by: 2026-03-31
```

3. For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it.
4. Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes.
5. Keep a compact LLM doc library with root anchors: `AGENTS.md`, `README.md`, and minimal canonical docs under `docs/` (`instructions`, `specs`, `reference-data`).
6. Delete integrated drafts on schedule; avoid `.archive/` mirrors in `docs/` unless retention is mandatory.

## Decision Tree

```text
User needs: [Documentation Task]
    ├─ Repo has a docs folder with many LLM-generated docs? → **Revamp Mode** (inventory → canonicalize → trim)
    ├─ New project? → **README.md**
    ├─ Technical decision? → **ADR**
    ├─ Building API? → **OpenAPI spec** + api-docs-template
    ├─ New version? → **CHANGELOG.md**
    ├─ Team collaboration? → **CONTRIBUTING.md**
    ├─ Documenting code? → **Docstrings** (JSDoc, Python)
    └─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
```

## Cross-Platform AI Documentation

### AGENTS.md Standard

Prefer `AGENTS.md` as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses `CLAUDE.md`), keep it aligned via a symlink only when you want identical content across tools.

```bash
# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md
```

## Do / Avoid

### Do

- Assign owners and review cadences to critical docs
- Add CI checks for links, style, and staleness
- Prefer small, task-oriented docs over big wiki pages
- Use Keep a Changelog format with semantic versioning

### Avoid

- Docs without owners (guaranteed to rot)
- Stale runbooks (dangerous during incidents)
- Copy/paste docs that drift from code

## LLM-First Documentation Patterns

When documentation is consumed primarily by AI agents (AGENTS.md, CLAUDE.md, canonical docs for coding assistants), stale docs become a distinct category of bug.

### Stale Docs = Agent Bugs

An agent reading stale docs will:
- Attempt to fix problems that are already solved (e.g., "9 open gating gaps" that were all sealed)
- Use wrong model names (e.g., "Claude Haiku" when code uses `gpt-4o`)
- Apply wrong limits (e.g., "fully gated" when free tier actually gets 3/week)
- Re-implement features that already exist

**Rule:** Treat doc updates as part of the feature PR, not as a follow-up task.

### Report Integration Lifecycle

Temporary investigation docs (QA reports, research exports, audit findings) must not become permanent false sources of truth.

Every dated report file must carry lifecycle metadata:

```yaml
---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---
```

Workflow:
1. Create report with `Status: pending-integration`
2. Extract durable findings into canonical docs
3. Mark report `Status: integrated` with date
4. Delete after `Delete-by` date (git history preserves everything)

### Living Docs: Audit Tables with Status Columns

Instead of deleting audit findings, add a Status column:

| Gap | Status | Sealed In |
|-----|--------|-----------|
| Chart aspects visible to free | Sealed | PR #26 |
| Dreams unlimited for free | Sealed | PR #26 |
| Ask Cosmos no rate limit | Open | — |

This preserves the audit trail while showing current state. Agents can quickly scan for `Open` items.

### Two-Pass Consolidation

When consolidating planning docs into canonical docs:

1. **First pass:** Follow the plan — extract content, delete source files, fix cross-references
2. **Second pass:** Audit deleted content against canonical destinations
   - `git show` deleted files to recover any unique data missed in planning
   - Compare code to docs for drift (e.g., feature marked "Planned" but code shows it's implemented)

Even thorough consolidation plans miss unique data that only lived in one source doc.

### Canonical Set Rule (No Doc Sprawl)

- One subject/feature should have one canonical doc.
- Derived docs must link to canonical docs instead of restating them.
- If a derived doc is fully integrated, mark it `integrated` and remove it by `delete_by` (default: delete, not archive).
- If two canonical docs overlap, merge and leave a redirect note in the removed file path.

### Canonical LLM Library Rule

- Root files are mandatory anchors: `AGENTS.md` for agent behavior/instructions and `README.md` for project navigation.
- The `docs/` folder should expose only a small canonical set for LLM consumption: current instruction sets, current specs, and durable reference data.
- Research logs, exploratory prompts, and intermediate drafts are temporary working files, not library entries.
- Keep discovery breadcrumbs as links from canonical docs; do not duplicate full research dumps.

### Anti-Fluff Rewrite Gate

Before merging LLM-generated docs, require:
- explicit audience and decision/use-case for each section
- measurable statements instead of vague claims
- source links + dates for external facts
- removal of duplicated paragraphs and "future ideas" not tied to a tracked decision

### Staleness Disclaimers Over Wrong Numbers

For externally-sourced data (competitor pricing, API rate limits, third-party capabilities):

```markdown
> Prices as of Feb 2026 — verify current pricing at [source].
```

A staleness disclaimer is safer than a potentially wrong number. Wrong numbers in agent-consumed docs cause incorrect implementation decisions.

### Decision Log Collision Prevention

When adding entries to a decision log (e.g., `### D039 — Feature Name`):

```bash
# Always check the latest entry number before adding
grep -o '### D[0-9]*' docs/decision-log.md | tail -1
```

Numbering collisions happen when two decisions are logged in rapid succession without checking.

## Backlog Status Sync Pattern (Mandatory)

When implementation status changes (for example backlog milestones completed), sync canonical docs in the same delivery cycle to prevent stale guidance for humans and agents.

### Sync Rules

1. Update one canonical status source first (feature matrix / roadmap / decision log).
2. Propagate only by reference links in secondary docs; avoid duplicate status prose.
3. Add concrete completion dates and owner for status changes.
4. If temporary reports are integrated, mark lifecycle state (`integrated` or `superseded`) and `delete_by`.

### Release Gate

A feature is not doc-complete until:
- canonical status doc updated,
- dependent docs checked for conflicting claims,
- docs sync checklist completed.

## Resources

| Resource | Purpose |
|----------|---------|
| [references/readme-best-practices.md](references/readme-best-practices.md) | README structure, badges |
| [references/adr-writing-guide.md](references/adr-writing-guide.md) | ADR lifecycle, examples |
| [references/changelog-best-practices.md](references/changelog-best-practices.md) | Keep a Changelog format |
| [references/api-documentation-standards.md](references/api-documentation-standards.md) | REST, GraphQL, gRPC docs |
| [references/code-commenting-guide.md](references/code-commenting-guide.md) | Docstrings, inline comments |
| [references/contributing-guide-standards.md](references/contributing-guide-standards.md) | CONTRIBUTING.md structure |
| [references/docs-as-code-setup.md](references/docs-as-code-setup.md) | MkDocs, Docusaurus, CI/CD |
| [references/writing-best-practices.md](references/writing-best-practices.md) | Clear communication |
| [references/markdown-style-guide.md](references/markdown-style-guide.md) | Markdown formatting |
| [references/documentation-testing.md](references/documentation-testing.md) | Vale, markdownlint, cspell |
| [references/ai-documentation-tools.md](references/ai-documentation-tools.md) | Mintlify, DocuWriter, GEO |
| [references/production-gotchas-guide.md](references/production-gotchas-guide.md) | Documenting platform issues |
| [references/documentation-metrics.md](references/documentation-metrics.md) | Doc quality, freshness, coverage scoring |
| [references/onboarding-documentation.md](references/onboarding-documentation.md) | Developer ramp-up guides, Day 1-Week 4 |
| [references/runbook-writing-guide.md](references/runbook-writing-guide.md) | Operational runbooks, incident response |
| [references/backlog-status-sync-pattern.md](references/backlog-status-sync-pattern.md) | Canonical backlog status sync workflow for multi-doc repos |

## Templates

| Category | Templates |
|----------|-----------|
| Architecture | [adr-template.md](assets/architecture/adr-template.md) |
| API Reference | [api-docs-template.md](assets/api-reference/api-docs-template.md) |
| Project Management | [readme-template.md](assets/project-management/readme-template.md), [changelog-template.md](assets/project-management/changelog-template.md), [contributing-template.md](assets/project-management/contributing-template.md) |
| Documentation Lifecycle | [template-doc-sync-checklist.md](assets/project-management/template-doc-sync-checklist.md) |
| Docs-as-Code | [docs-structure-template.md](assets/docs-as-code/docs-structure-template.md), [ownership-model.md](assets/docs-as-code/ownership-model.md) |

## Related Skills

| Skill | Purpose |
|-------|---------|
| [qa-docs-coverage](../qa-docs-coverage/SKILL.md) | Documentation gap audit |
| [dev-api-design](../dev-api-design/SKILL.md) | REST API patterns |
| [dev-git-workflow](../dev-git-workflow/SKILL.md) | Conventional Commits |
| [docs-ai-prd](../docs-ai-prd/SKILL.md) | PRD templates |

## Fact-Checking

- Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
- Prefer primary sources; report source links and dates for volatile information.
- If web access is unavailable, state the limitation and mark guidance as unverified.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/vasilyu1983) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->