作为代码的文档

1）建筑原则

1.真理的单一来源。文档，图表，API规范，词汇表-在代码旁边的VCS中。
2.自动质量检查。Linters，拼写，链接验证，doctest代码示例。
3.装配为人工制品。坞站，PDF/ebook，"内置提示"是发布的pipline的一部分。
4.转换和跟踪。Doc统治着改变系统行为的相同公关。ADR与Commites相关。
5.按角色可访问性。公共/内部，Runbook'和呼叫下，集成商的API支持。
6.手工操作最少。从源生成目录，方案，依赖项图，代码片段。

2）文件类型和回购结构

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC-在实施前讨论解决方桉。
• ADR是固定的体系结构解决方案（上下文→解决方案→ →替代方案的含义）。
• Runbook/Playbook-事件和操作的逐步说明。
• How-To/FAQ-任务→步骤→验证结果。
• API支架-OpenAPI/AsyncAPI/Proto作为SDK和码头的生成源。
• 图表作为代码是Mermaid/PlantUML/Graphviz/C4。

3）风格和标准

单一样式指南（色调、术语、标题模板、示例）。
带有规范术语（EN/RU），alias和禁止用语的词汇表。
编号和链接：永久锚点，ADR/RFC/代码之间的交叉参考。

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4）组装和出版

• MkDox（材料）-简单、方便、良好的导航和搜索。
• Docusaurus是文档和docs+博客的集合；MDX组件。
• Antora是大型平台的模块化文档。

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5）图表和图表作为代码

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI渲染到站点；其中生成了SDK/客户端/示例。

6）质量： linter和文档测试

• markdownlint-Markdown格式化规则。
• 淡水河谷-样式/术语/语气。
• Spellcheck是拼写（RU/EN字典）。
• Linkcheck-外部/内部链接，锚定。
• Doctest/Examples-执行代码片段,同步CLI/API版本。
• Schematest是OpenAPI/AsyncAPI/JSON Schema/Proto的验证。

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

CI运行"python -m doctest docs/snippets/calc。py`.

7）流程： RFC/ADR/评论和 SLA过时

RFC流：发起人→草稿→讨论→决定→计划→实施→事后复古。
ADR流：简要捕获选择+引用RFC/实验。

审查程序： 来源-"CODEOWNERS"+"doc-owners。yaml`.

SLA过时：关键文章在N日后有 "last_review"和评论。

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8）本地化（i18n）和多语种

本地化策略：源语言（EN或RU）→ "i18n/< locale>分支"翻译。
密钥和上下文：为标题/片段存储"stable-ID"。
检查："missing-keys"步骤，异步同步。
区域样式：本地词汇表、无效方程式、本地UI语言代码示例。

9）产品集成

内置帮助（in-app docs）： MDX组件、上下文提示。
按发行版排序：docs/vX标签/分支。Y'，具有选择器版本的网站。
自我生成部分：来自OpenAPI/AsyncAPI、GraphQL SDL、CLI "-help"。
Changelog作为代码：通过PR标签自动生成（功能/fix/docs/breaking）。

10）度量指标和文档的可观察性

Docs SLO：组装/发布时间，站点上限，公关后文档出现时间。
人工制品覆盖率：具有ADR的服务比例，具有示例的残局比例，具有"健康检查"的Runbook's份额。
自定义指标：无响应搜索查询、查看深度、内置提示的CTR。
质量：linter/1000行错误，"位链接"，陈旧文章的比例。

11）安全和隐私

回购中禁止秘密和PD；linters秘密和伪装。
通过SSO访问内部站点；公共部门是分开的。
导出规则：没有内部链接的PDF/存档,敏感文档的水印。
截图卫生：自动匿名（moc-data/blur）。

12）模式

Docs in PR.影响行为的任何更改都涉及在相同的PR中更新码头。
模板作为合同。通过放置码头工件的发电机创建服务/端口/数据网。
图表作为代码。任何图案都是可编辑的源代码，即CI中的SVG/PNG组件。
Docs Preview.机器人的评论参考了该网站的公关预览。
代码中的坞站链接。将渲染到站点的来源注释（'@doc：adr/0007'）。

13）反模式

Wiki/Notion中没有代码旁边版本的文档→同步。
没有源代码的截图→无法自动更新。
口头聊天和私人文件中的"秘密"知识。
没有示例和不变量的生成器→无用的页面。
缺少业主和"last_review" →过时的雪崩。
手动组装和发布→易碎且罕见的码头版本。

14）自动化示例

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15）建筑师支票清单

1.代码旁边是否有一个单一的存储库,并且结构清晰?

2.描述了模板（RFC/ADR/Runbook/How-To）和词汇表?

3.包括linters（markdownlint，Vale），spellcheck，linkcheck和doctest？

4.图表和图表-如何代码,构建在CI?

5.API spacks （OpenAPI/AsyncAPI/Proto）是否被验证并渲染到站点?

6.组织公关文档预览和按商品自动发布?

7.是否有SLA过时（last_review）和"所有者"页面?

8.度量标准： 覆盖范围,linter错误,位链接,搜索"零"查询?

9.安全政策： 秘密禁止,SSO,水印/出口?

10.本地化是否由分支机构管理并检查通行证？

二.结论

Docs-as-Code将文档从"事后注释"转换为工作开发工件：可验证，可测试和可交付。通过这种方法，知识与代码并存，更改是透明的，用户和工程师在需要时会收到最新的指令，模式和示例。这降低了运营风险，加快了爬坡速度，并提高了整个平台的决策质量。