作為代碼的文檔

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將文檔從「事後註釋」轉換為工作開發工件：可驗證，可測試和可交付。通過這種方法，知識與代碼並存，更改是透明的，用戶和工程師在需要時會收到最新的指令，模式和示例。這降低了運營風險，加快了爬坡速度，並提高了整個平臺的決策質量。