Documentation Patterns
Templates and opinionated structures for technical documentation -- READMEs, Architecture Decision Records, OpenAPI specs, changelogs, and writing style. Each category has individual rule files in rules/ loaded on-demand.
Quick Reference
| Category |
Rule |
Impact |
When to Use |
| README |
1 |
HIGH |
Starting a project, onboarding contributors |
| ADR |
1 |
HIGH |
Recording architecture decisions |
| API Docs |
1 |
HIGH |
Documenting REST APIs with OpenAPI 3.1 |
| Changelog |
1 |
MEDIUM |
Maintaining release history |
| Writing Style |
1 |
MEDIUM |
Any technical writing task |
Total: 5 rules across 5 categories
Quick Start
## README Skeleton
# Project Name
Brief description -> Quick Start -> Installation -> Usage -> API -> Config -> Contributing -> License
## ADR Format
# ADR-001: Title
Status -> Context -> Decision -> Consequences (positive/negative) -> References
## OpenAPI Minimum
openapi: 3.1.0 with info, paths, components/schemas, error responses
## Changelog Entry
## [1.2.0] - 2026-03-05
### Added / Changed / Deprecated / Removed / Fixed / Security
## Writing Rule of Thumb
Active voice, present tense, second person, one idea per sentence
README
Complete README template with all essential sections for open-source and internal projects.
docs-readme-structure -- Project name, quick start, installation, usage, API reference, configuration, contributing, license
Architecture Decision Records
Structured format for capturing architectural decisions with context and consequences.
docs-adr-template -- Status, context, decision, consequences (positive/negative), references
API Documentation
OpenAPI 3.1 specification patterns for consistent, machine-readable API docs.
docs-api-openapi -- Path structure, operation definitions, schema components, error responses (RFC 9457)
Changelog
Keep a Changelog format for curated, human-readable release history.
docs-changelog-format -- Added, Changed, Deprecated, Removed, Fixed, Security sections with semver
Writing Style
Technical writing conventions for clear, scannable documentation.
docs-writing-style -- Active voice, present tense, concise sentences, API doc checklist
Related Skills
ork:api-design -- API design patterns (complements OpenAPI documentation)ork:architecture-decision-record -- ADR workflow and lifecycleork:release-management -- Release process including changelog updates
Version: 1.0.0 (March 2026)
1---2name: documentation-patterns3description: Technical documentation patterns for READMEs, ADRs, API docs (OpenAPI 3.1), changelogs, and writing style guides. Use when creating project documentation, writing architecture decisions, documenting APIs, or maintaining changelogs.4license: MIT5---6
7# Documentation Patterns
8
9Templates and opinionated structures for technical documentation -- READMEs, Architecture Decision Records, OpenAPI specs, changelogs, and writing style. Each category has individual rule files in `rules/` loaded on-demand.
10
11## Quick Reference
12
13| Category | Rule | Impact | When to Use |
14|----------|------|--------|-------------|
15| [README](#readme) | 1 | HIGH | Starting a project, onboarding contributors |
16| [ADR](#architecture-decision-records) | 1 | HIGH | Recording architecture decisions |
17| [API Docs](#api-documentation) | 1 | HIGH | Documenting REST APIs with OpenAPI 3.1 |
18| [Changelog](#changelog) | 1 | MEDIUM | Maintaining release history |
19| [Writing Style](#writing-style) | 1 | MEDIUM | Any technical writing task |
20
21**Total: 5 rules across 5 categories**
22
23## Quick Start
24
25```markdown
26## README Skeleton
27# Project Name
28Brief description -> Quick Start -> Installation -> Usage -> API -> Config -> Contributing -> License
29
30## ADR Format
31# ADR-001: Title
32Status -> Context -> Decision -> Consequences (positive/negative) -> References
33
34## OpenAPI Minimum
35openapi: 3.1.0 with info, paths, components/schemas, error responses
36
37## Changelog Entry
38## [1.2.0] - 2026-03-05
39### Added / Changed / Deprecated / Removed / Fixed / Security
40
41## Writing Rule of Thumb
42Active voice, present tense, second person, one idea per sentence
43```
44
45## README
46
47Complete README template with all essential sections for open-source and internal projects.
48
49- **`docs-readme-structure`** -- Project name, quick start, installation, usage, API reference, configuration, contributing, license
50
51## Architecture Decision Records
52
53Structured format for capturing architectural decisions with context and consequences.
54
55- **`docs-adr-template`** -- Status, context, decision, consequences (positive/negative), references
56
57## API Documentation
58
59OpenAPI 3.1 specification patterns for consistent, machine-readable API docs.
60
61- **`docs-api-openapi`** -- Path structure, operation definitions, schema components, error responses (RFC 9457)
62
63## Changelog
64
65Keep a Changelog format for curated, human-readable release history.
66
67- **`docs-changelog-format`** -- Added, Changed, Deprecated, Removed, Fixed, Security sections with semver
68
69## Writing Style
70
71Technical writing conventions for clear, scannable documentation.
72
73- **`docs-writing-style`** -- Active voice, present tense, concise sentences, API doc checklist
74
75## Related Skills
76
77- `ork:api-design` -- API design patterns (complements OpenAPI documentation)
78- `ork:architecture-decision-record` -- ADR workflow and lifecycle
79- `ork:release-management` -- Release process including changelog updates
80
81**Version:** 1.0.0 (March 2026)
yonatangross