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)