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 lifecycle
ork:release-management -- Release process including changelog updates
Version: 1.0.0 (March 2026)
1---
2name: documentation-patterns
3license: MIT
4compatibility: "Claude Code 2.1.251+."
5description: 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.
6tags: [documentation, readme, adr, api-docs, openapi, changelog, writing-style, technical-writing]
7version: 1.0.0
8author: OrchestKit
9user-invocable: false
10disable-model-invocation: true
11context: inherit
12agent: release-engineer
13complexity: low
14persuasion-type: reference
15effort: low
16allowed-tools:
17 - Read
18 - Glob
19 - Grep
20metadata:
21 source: https://skillmd.com/skills/yonatangross/documentation-patterns
22---
23
24# Documentation Patterns
25
26Templates 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.
27
28## Quick Reference
29
30| Category | Rule | Impact | When to Use |
31|----------|------|--------|-------------|
32| [README](#readme) | 1 | HIGH | Starting a project, onboarding contributors |
33| [ADR](#architecture-decision-records) | 1 | HIGH | Recording architecture decisions |
34| [API Docs](#api-documentation) | 1 | HIGH | Documenting REST APIs with OpenAPI 3.1 |
35| [Changelog](#changelog) | 1 | MEDIUM | Maintaining release history |
36| [Writing Style](#writing-style) | 1 | MEDIUM | Any technical writing task |
37
38**Total: 5 rules across 5 categories**
39
40## Quick Start
41
42```markdown
43## README Skeleton
44# Project Name
45Brief description -> Quick Start -> Installation -> Usage -> API -> Config -> Contributing -> License
46
47## ADR Format
48# ADR-001: Title
49Status -> Context -> Decision -> Consequences (positive/negative) -> References
50
51## OpenAPI Minimum
52openapi: 3.1.0 with info, paths, components/schemas, error responses
53
54## Changelog Entry
55## [1.2.0] - 2026-03-05
56### Added / Changed / Deprecated / Removed / Fixed / Security
57
58## Writing Rule of Thumb
59Active voice, present tense, second person, one idea per sentence
60```
61
62## README
63
64Complete README template with all essential sections for open-source and internal projects.
65
66- **`docs-readme-structure`** -- Project name, quick start, installation, usage, API reference, configuration, contributing, license
67
68## Architecture Decision Records
69
70Structured format for capturing architectural decisions with context and consequences.
71
72- **`docs-adr-template`** -- Status, context, decision, consequences (positive/negative), references
73
74## API Documentation
75
76OpenAPI 3.1 specification patterns for consistent, machine-readable API docs.
77
78- **`docs-api-openapi`** -- Path structure, operation definitions, schema components, error responses (RFC 9457)
79
80## Changelog
81
82Keep a Changelog format for curated, human-readable release history.
83
84- **`docs-changelog-format`** -- Added, Changed, Deprecated, Removed, Fixed, Security sections with semver
85
86## Writing Style
87
88Technical writing conventions for clear, scannable documentation.
89
90- **`docs-writing-style`** -- Active voice, present tense, concise sentences, API doc checklist
91
92## Related Skills
93
94- `ork:api-design` -- API design patterns (complements OpenAPI documentation)
95- `ork:architecture-decision-record` -- ADR workflow and lifecycle
96- `ork:release-management` -- Release process including changelog updates
97
98**Version:** 1.0.0 (March 2026)