ドキュメントをコードとして

1）建築の原則

1.真実の単一の源。ドキュメント、図、図、API仕様、用語集-コードの横にあるVCSで。
2.自動質の点検。Linters、スペルチェック、リンクチェック、Doctestコード例。
3.アーティファクトとしてアセンブリ。ドッキングサイト、PDF/ebook、「組み込みヒント」-リリースパイプラインの一部。
4.バージョン管理とトレーサビリティ。Docはシステムの動作を変更する同じPRを規則化します。ADRはコミットバインドされます。
5.役割による可用性。Public/internal、 Runbook、 on-call、インテグレータの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）、エイリアス、禁止された製剤を含む用語集。
番号付けと参照：永久アンカー、ADR/RFC/コード間のクロスリファレンス。

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

4）アセンブリおよび出版物

• MkDocs（素材）-シンプルで便利で、良いナビゲーションと検索。
• Docusaurus-ドキュメントのバージョンとドキュメント+ブログ。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/clients/examplesはそれらから生成されます。

6）質： リンターおよびドキュメンテーションテスト

• markdownlint-Markdown書式設定ルール。
• Vale-スタイル/用語/トーン。
• スペルチェック-スペル（RU/EN辞書）。
• Linkcheck-外部/内部リンク、アンカー。
• Doctest/Examples-コードスニペットの実行、CLI/APIバージョンの同期。
• Schematest-OpenAPI/AsyncAPI/JSONスキーマ/プロトバリデーション。

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フロー：initiator→draft copy→discussion→decision→plan→implementation→retro post facto。
ADRフロー：RFC/実験の選択+参照を簡単に修正します。

レビュー手順： source-'CODEOWNERS'+'doc-owners。ヤムル・・・

廃止のためのSLA：重要な記事には「last_review」があり、N日間でレビューを警告します。

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）製品の統合

組み込みヘルプ（アプリ内ドキュメント）：MDXコンポーネント、コンテキストヒント。
リリースによるバージョン管理：tags/branchesのdocs/vX。Y'、セレクターバージョンのサイト。
セクションの自動生成：OpenAPI/AsyncAPI、 GraphQL SDL、 CLI '--help'から。
コードとしての変更履歴：PRラベルによる自動生成（feat/fix/docs/breaking）。

10）ドキュメントの指標と観測可能性

ドキュメントSLO：ビルド/パブリッシュ時間、サイトの稼働時間、PR後のドキュメントの表示時間。
アーティファクト・カバレッジ：ADRとのサービスの共有、エンドポイントの共有と例、Runbooksの共有と「ヘルスチェック」。
ユーザーメトリック：未回答の検索、表示深さ、組み込みプロンプトのCTR。
品質：リンターエラー/1000行、「壊れたリンク」、古い記事の割合。

11）セキュリティとプライバシー

秘密とPDはリポジトリで禁止されています。秘密とマスキングのためのリンク。
SSOを介して内部サイトへのアクセス。パブリックセクションは分離されました。
輸出規則：内部リンクのないPDF/アーカイブ、機密文書の透かし。
スクリーンショットの衛生：自動匿名化（mok data/blur）。

12）パターン

PRのドキュメント。どのような変更でも、同じPRでドックを更新する必要があります。
契約としてのテンプレート。サービス/エンドポイント/データセットの作成-ドックブランクを置くジェネレータを介して。
コードとしてのチャート。任意の画像-編集可能なソース、CIのSVG/PNGアセンブリ。
ドキュメントのプレビュー。PRのためのサイトプレビューへのリンクを持つボットコメント。
コード内のドッキングリンク。サイトにレンダリングされたソース（'@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）、スペルチェック、linkcheckとdoctest？
4.図と図-コード、CIでのアセンブリのような？
5.API仕様（OpenAPI/AsyncAPI/Proto）は検証され、サイトにレンダリングされますか？
6.PRのためのdocs-previewとマージによる自動パブリッシュを組織しましたか？
7.ページの老朽化したSLA （last_review）と「所有者」はありますか？
8.メトリクス：カバレッジ、リンターエラー、リンク切れ、検索「ゼロ」クエリ？
9.セキュリティポリシー：禁止された秘密、SSO、透かし/エクスポート？
10.ローカライズはブランチによって制御され、省略がないかチェックされますか？

おわりに

Docs-as-Codeはドキュメントを「ポストファクトノート」から、バージョン管理、テスト、納品という開発の作業アーティファクトに変換します。このアプローチでは、知識はコードの隣にあり、変更は透明であり、ユーザーとエンジニアは必要に応じて最新の指示、図、例を受け取ります。これにより、運用上のリスクを軽減し、オンボーディングを迅速化し、プラットフォーム全体のソリューションの品質を向上させます。