documentation-patterns
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)
More from yonatangross/orchestkit
responsive-patterns
Responsive design with Container Queries, fluid typography, cqi/cqb units, subgrid, intrinsic layouts, foldable devices, and mobile-first patterns for React applications. Use when building responsive layouts or container queries.
464ui-components
UI component library patterns for shadcn/ui and Radix Primitives. Use when building accessible component libraries, customizing shadcn components, using Radix unstyled primitives, or creating design system foundations.
443devops-deployment
Use when setting up CI/CD pipelines, containerizing applications, deploying to Kubernetes, or writing infrastructure as code. DevOps & Deployment covers GitHub Actions, Docker, Helm, and Terraform patterns.
401rag-retrieval
Retrieval-Augmented Generation patterns for grounded LLM responses. Use when building RAG pipelines, embedding documents, implementing hybrid search, contextual retrieval, HyDE, agentic RAG, multimodal RAG, query decomposition, reranking, or pgvector search.
340architecture-decision-record
Use this skill when documenting significant architectural decisions. Provides ADR templates following the Nygard format with sections for context, decision, consequences, and alternatives. Use when writing ADRs, recording decisions, or evaluating options.
326domain-driven-design
DDD tactical patterns for complex business modeling including entities, value objects, aggregates, domain services, repositories, specifications, and bounded contexts. Python dataclass implementations with TypeScript alternatives. Use when building rich domain models, enforcing invariants, or separating domain logic from infrastructure.
326