illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 writethedocs.org 与 keepachangelog.com 编写 —— 文档类型矩阵 / OpenAPI / CHANGELOG / 图表工具对照 / 写作原则 / 工具链

文档类型矩阵 ​

类型受众目的关键产物规范/工具
API 文档集成者零摩擦使用 APIspec + 交互文档OpenAPI / Redoc
架构文档团队/新人解释设计与决策设计文档 + ADR + 图C4 模型 / ADR
README所有人30 秒决策项目门面Standard README
CHANGELOG使用者升级有预期变更记录Keep a Changelog
技术博客社区/同行经验外溢长文 + 示例Markdown / MDX
教程新手手把手学会step-by-step渐进式示例
参考手册资深用户查阅细节全 API/配置自动生成
运行手册 Runbook运维应急处置故障流程SOP 模板

OpenAPI 速查 ​

结构骨架 ​

yaml
openapi: 3.1.0          # 版本
info:                    # 元信息
  title: ...
  version: ...
  description: ...
servers:                 # 服务器地址
  - url: https://api.example.com/v1
paths:                   # 路径与操作
  /resource:
    get:
      summary: ...
      parameters: ...
      responses: ...
components:              # 可复用组件
  schemas:
    Model: ...
  securitySchemes: ...
security:                # 全局安全
  - ApiKeyAuth: []
tags: []                 # 分组

常用工具 ​

工具用途
Swagger UI交互式 API 文档（可试调）
Redoc美观的只读 API 文档
openapi-generator生成 SDK / 服务端桩
PrismMock 服务
Spectral / vacuumOpenAPI lint / 规范检查
Stoplight Studio可视化 OpenAPI 编辑器

CHANGELOG 速查 ​

Keep a Changelog 六类 ​

类别何时用
Added新增功能
Changed现有功能变更（非新增非修复）
Deprecated标记即将移除
Removed本次移除（通常先 Deprecated）
Fixedbug 修复
Security安全漏洞修复

完整模板 ​

markdown
# Changelog

All notable changes to this project will be documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- ...

## [1.2.0] - 2026-07-15

### Added
- 批量导出（CSV/Excel）

### Changed
- 默认分页 20 → 50

### Deprecated
- `/orders/list` 废弃，用 `/orders`

### Fixed
- 时区导致日期错位

### Security
- 修复 SQL 注入（CVE-2026-xxxx）

## [1.1.0] - 2026-05-10
...

Conventional Commits type 对照 ​

type说明进 CHANGELOGSemVer
feat新功能AddedMINOR
fixbug 修复FixedPATCH
BREAKING CHANGE / feat!破坏性ChangedMAJOR
docs文档不进-
style格式不进-
refactor重构不进-
perf性能perf（视工具）PATCH
test测试不进-
build / ci / chore工程类不进-

提交示例：

feat(orders): 支持批量导出 CSV

新增 GET /orders/export 端点，异步生成下载链接。

Closes #123

Diagrams as Code 工具对照 ​

全面对照 ​

维度MermaidPlantUMLD2
语法Markdown 内嵌 / 类 JSJava 风格 DSL现代声明式
渲染浏览器原生（JS）服务端（Java）本地/CLI（Go）
GitHub 渲染原生支持需插件/Action需 Action
UML 完整度中（常见图）全（UML 标杆）中
美观度中中高（现代设计）
自动布局有限有限强（多引擎）
主题有限有限丰富（设计师主题）
导出SVG/PNGSVG/PNG/PDFSVG/PNG/PDF
Sketch 手绘风无无有
生态成熟度高（社区广）高（企业）新兴
学习曲线低中低-中

支持的图类型 ​

图类型MermaidPlantUMLD2
流程图 Flowchart✅✅✅
时序图 Sequence✅✅✅
类图 Class✅✅✅
状态图 State✅✅✅
实体关系 ER✅✅✅
甘特图 Gantt✅✅❌
饼图 Pie✅❌❌
思维导图 Mindmap✅❌❌
组件/部署图✅✅（UML 部署图）✅
网络架构有限有限强

选型决策 ​

图要内嵌 GitHub README/Wiki？
├─ 是 → Mermaid（原生渲染）
└─ 否 → 需要标准 UML？
        ├─ 是 → PlantUML
        └─ 否 → 需要演示级美观？
                ├─ 是 → D2
                └─ 否 → Mermaid（默认，生态最广）

写作原则速查 ​

受众先行 ​

写之前问三个问题：

  1. 读者是谁？（初级/资深/外部/非技术）
  2. 他们已经知道什么？（背景假设）
  3. 他们需要知道什么？（目标）

主动 vs 被动语态 ​

被动（避免）主动（推荐）
The error is returned by the systemThe system returns the error
Configuration should be modifiedModify the configuration
It is recommended thatWe recommend

术语一致性 ​

  • 建术语表（glossary），定义关键术语
  • 全篇同一概念用同一个词
  • 中英文混用要统一（要么全「端点」要么全「endpoint」）

简洁原则 ​

  • 一句话表达一个意思
  • 列表优于长段落
  • 示例配抽象描述
  • 删掉「非常」「十分」「基本上」等填充词

SemVer 速查 ​

MAJOR.MINOR.PATCH
变更类型影响位示例
不兼容 API 变更MAJOR1.2.3 → 2.0.0
兼容新功能MINOR1.2.3 → 1.3.0
bug 修复PATCH1.2.3 → 1.2.4
预发布后缀1.0.0-alpha.1
构建元数据+后缀1.0.0+exp.sha.5114f85

规则：一旦发布，该版本号内容不可变；后续变更只能递增新版本。

文档质量五要素（writethedocs） ​

要素含义检查方法
可发现 Discoverable读者能找到搜索/导航是否顺畅
可读 Readable找到能读懂受众测试、结构清晰
准确 Accurate内容正确专家审、代码示例可运行
及时 Current与产品同步Docs as Code、更新日期标记
连贯 Coherent风格一致风格指南、术语表、lint

写作工具链全表 ​

环节工具
编辑VS Code / Obsidian / HackMD
Markdown 扩展MDX（组件嵌入）/ reST / AsciiDoc
图表Mermaid / PlantUML / D2 / Excalidraw
静态站点VitePress / Docusaurus / MkDocs Material / Antora / docsify
API 文档Redoc / Swagger UI / Stoplight
CI 检查markdownlint / vale / cspell / markdown-link-check / lychee
CHANGELOGstandard-version / semantic-release / changesets / lerna
协作Git PR / GitHub Review / Notion / Confluence
翻译 i18nCrowdin / Lokalise（Docusaurus 原生支持）
分析Google Analytics / Plausible（阅读量）

参考 ​