# Decide Docs Site

> When to keep docs in README vs build a dedicated docs site. Documentation strategy.

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

---


# Skill: Documentation Strategy

> "The README is a landing page, not a manual."

## The Decision

**README-only when:**
- Simple package with minimal configuration (`translatable`, `responsecache`)
- Fewer than 15 config keys
- 1-3 code examples cover all use cases
- Package has fewer than 3k stars (community doesn't demand depth)

**Docs site when:**
- Significant configuration surface area (`medialibrary`: 40+ config keys)
- Multiple usage patterns that need separate pages
- More than 3k stars (community expects depth)
- Advanced usage would bloat the README
- Upgrade guides span multiple major versions

## The Heuristic

Ask: *"Does the README scroll for more than 3 screens?"*

If yes, move depth to a docs site. Keep the README as a landing page + quick start.

## The Quick Test

| Ask                                            | Answer | Use         |
|------------------------------------------------|--------|-------------|
| Can you explain all features in 3 code blocks? | Yes    | README-only |
| More than 15 config keys?                      | Yes    | Docs site   |
| More than 3k GitHub stars?                     | Yes    | Docs site   |
| Multiple distinct usage patterns?              | Yes    | Docs site   |
| Does the README scroll past 3 screens?         | Yes    | Docs site   |
| Is upgrade documentation needed?               | Yes    | Docs site   |

**See also:** craft-docs (how to structure a docs site once you decide to build one), craft-readme (keeping the README tight as a landing page).

## Real-World Examples

See [examples.md](examples.md).