Back to Details

documentation-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
面向技术文档的模板与规范化结构——涵盖README、架构决策记录（Architecture Decision Records，ADR）、OpenAPI规范、变更日志及写作风格。每个分类在
rules/
目录下都有独立的规则文件，可按需加载。

Quick Reference

快速参考

CategoryRuleImpactWhen to Use
README1HIGHStarting a project, onboarding contributors
ADR1HIGHRecording architecture decisions
API Docs1HIGHDocumenting REST APIs with OpenAPI 3.1
Changelog1MEDIUMMaintaining release history
Writing Style1MEDIUMAny technical writing task
Total: 5 rules across 5 categories
分类规则影响程度适用场景
README1高启动项目、新贡献者入职引导
架构决策记录1高记录架构决策
API文档1高用OpenAPI 3.1编写REST API文档
变更日志1中维护版本发布历史
写作风格1中任何技术写作任务
总计：5个分类共5条规则

Quick Start

快速开始

markdown
undefined
markdown
undefined

README Skeleton

README模板骨架

Project Name

项目名称

Brief description -> Quick Start -> Installation -> Usage -> API -> Config -> Contributing -> License
简要描述 -> 快速开始 -> 安装 -> 使用方法 -> API -> 配置 -> 贡献指南 -> 许可证

ADR Format

ADR格式

ADR-001: Title

ADR-001: 标题

Status -> Context -> Decision -> Consequences (positive/negative) -> References
状态 -> 背景 -> 决策 -> 影响（正面/负面） -> 参考资料

OpenAPI Minimum

OpenAPI最小规范

openapi: 3.1.0 with info, paths, components/schemas, error responses
openapi: 3.1.0 with info, paths, components/schemas, error responses

Changelog Entry

变更日志条目

[1.2.0] - 2026-03-05

[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
undefined
主动语态、现在时态、第二人称、每句表达一个观点
undefined

README

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
适用于开源项目与内部项目的完整README模板，包含所有核心章节。
  • docs-readme-structure
     -- 项目名称、快速开始、安装、使用方法、API参考、配置、贡献指南、许可证

Architecture Decision Records

架构决策记录

Structured format for capturing architectural decisions with context and consequences.
  • docs-adr-template
     -- Status, context, decision, consequences (positive/negative), references
用于记录架构决策的结构化格式，包含背景与影响。
  • docs-adr-template
     -- 状态、背景、决策、影响（正面/负面）、参考资料

API Documentation

API文档

OpenAPI 3.1 specification patterns for consistent, machine-readable API docs.
  • docs-api-openapi
     -- Path structure, operation definitions, schema components, error responses (RFC 9457)
用于构建一致、机器可读API文档的OpenAPI 3.1规范模式。
  • docs-api-openapi
     -- 路径结构、操作定义、Schema组件、错误响应（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
采用Keep a Changelog格式，打造精心整理、易于人类阅读的版本发布历史。
  • docs-changelog-format
     -- 基于语义化版本（semver）的新增、变更、弃用、移除、修复、安全更新章节

Writing Style

写作风格

Technical writing conventions for clear, scannable documentation.
  • docs-writing-style
     -- Active voice, present tense, concise sentences, API doc checklist
面向清晰、易浏览文档的技术写作规范。
  • docs-writing-style
     -- 主动语态、现在时态、简洁语句、API文档检查清单

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)
  • ork:api-design
    -- API设计模式（补充OpenAPI文档相关内容）
  • ork:architecture-decision-record
    -- ADR工作流与生命周期
  • ork:release-management
    -- 版本发布流程，含变更日志更新
版本： 1.0.0（2026年3月）