attac-t Skill: Craft Docs
"Good documentation is a layered cake. A developer should be able to stop at any layer and walk away with enough to ship."
The Standard
docs/directory in the repo: Markdown files that feed a docs renderer. Thedocs/directory appears when the package matures. Not every package needs one -- but every package with significant configuration surface area does.Frontmatter with weight ordering:
weight: Ncontrols page order. Weight ordering keeps docs sorted without relying on filenames.Progressive depth: Introduction, then basic usage, then advanced usage, then API reference. Each layer is self-contained. A developer can stop at "basic usage" and have a working integration.
Layer Location Content Pitch README first screenful What it does + 1-2 line code example Quick start introduction.mdInstall + basic usage Features basic-usage/Individual feature pages Customization advanced-usage/Custom implementations, extending interfaces Never dump all features at once. Simple things simple, complex things possible.
UPGRADING.md: Reverse-chronological. Actionable bullet points, not essays. Before/after code examples. Full migration scripts when schema changes. Rate each breaking change as High/Medium/Low likelihood of impact. Developers need to triage -- not read every line.
Config shown in installation docs: The developer sees exactly what they are getting before publishing. Show the full config file with inline comments. No surprises after
php artisan vendor:publish.Anticipate the wall: Put warnings BEFORE the step that will trigger the error, not after. If a database user needs to adjust something, say so before the migration step -- not in a troubleshooting section they will find 20 minutes later.
Versioned docs: Maintain separate docs per major version. Old docs remain accessible. When a version reaches end-of-life, state it clearly.
Automated migration guidance: Where possible, include Rector rules or codemods for major version upgrades. Automation beats manual find-and-replace. Laravel Shift's approach with
driftingly/rector-laravelis the gold standard -- version-specific rule sets and cumulative level sets.
The Approaches
Filament's versioned docs: Every major version gets its own branch and docs. Automated upgrade scripts (filament/upgrade) rewrite application code for breaking changes. This dramatically lowers the cost of major versions.
Docs-as-website: The docs/ directory feeds a docs renderer. Frontmatter carries version, slogan, and repo metadata. Each package version gets its own docs set.
The Anti-Patterns
| Don't | Do | Why |
|---|---|---|
| Warnings after the failure step | Warnings before the step | Developers read linearly -- catch them before they fall |
| Upgrade guides without code examples | Before/after code in every breaking change | "Renamed X to Y" means nothing without code |
| Flat docs with no progressive depth | Layered structure: intro, basic, advanced | Developers have different depth needs |
| Abandon docs for previous versions | Maintain versioned docs with clear EOL | Users on older versions still need documentation |
| Hide config until after publish | Show full config in installation docs | No surprises -- informed decisions before commitment |
| Upgrade guide as a wall of text | Impact-rated changes: High/Medium/Low | Developers triage -- help them prioritize |
| Skip automated migration guidance | Include Rector rules or codemods where possible | Automation beats manual find-and-replace |
See also: decide-docs-site (when to build a docs site vs README-only), craft-deprecation (UPGRADING.md patterns).
Real-World Examples
See examples.md.