{"canonical_url":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/","content_markdown":"# 文書を独自の静的検査で管理\n\n文書に、引き下げのみ可能なファイル別行数上限、目次要件、実在パス検査を設けた。完了扱いの9計画中6計画に未完了項目があり、コミットを制御する14タスクがどの文書にも記載されていないことを検出した。\n\n8月 2026\n\n**状況.** 品質、デザイン、アクセシビリティ、印刷、メタデータ、翻訳、gitを26文書の指示で管理していた。指示は長くなり、コードからずれ、移動したファイルを参照し、一定の長さで読まれなくなる。読まれない規則は規則として働かない。\n\n**課題.** 助言でなく失敗する上限を持つ静的検査を設け、文書もコードと同じように扱う必要があった。\n\n**行動.** 8つの機械的な方針を設けた。文書長の絶対上限と警告する目安、縮むだけで戻らないファイル別行数予算、大きさに応じた全体目次・節目次、主題の担当文書を定める配置規則、リンク妥当性、主張とチェック欄が一致する計画の正直さ、コミットを制御する全タスクの文書記載、記したパスとコード記号の実在検査だった。初回で、未完了欄付きの完了6計画、どこにも記載のない14タスク、リンク切れ3件、孤立文書1件、5文書にまたがる死んだパス3件を検出し、必要性を示した。その後、この仕事の説明を開発文書へ加えると上限に達し、作成者自身を拒否して別文書が生まれた。意図どおりの働きだった。\n\n**結果.** 計約2,666実効行の26文書が、増やせない予算下に入り、全パスと記号を実ツリーに照合するようになった。毎コミットを止める14検査が一切記載されていなかったという、機械の規則と人が読む規則の分離こそ、繰り返す価値のある不都合な発見だった。\n\n---\n\n- 役割: テクニカルプロダクトマネージャー\n- カテゴリー: [自動化・CI/CD](https://engineer.company/ja/categories/automation/), [テスト・品質保証](https://engineer.company/ja/categories/testing/), [Python](https://engineer.company/ja/categories/python/), [技術面の統率](https://engineer.company/ja/categories/technical-leadership/), [プロジェクト管理](https://engineer.company/ja/categories/project-management/), [文書作成](https://engineer.company/ja/categories/documentation/)\n- サービス: [技術面の統率・コンサルティング](https://engineer.company/ja/services/technical-leadership/), [プロジェクト管理（アジャイル）](https://engineer.company/ja/services/project-management/), [技術文書の作成](https://engineer.company/ja/services/technical-documentation/)\n\n\u003chttps://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"計約2,666実効行の26文書が、増やせない予算下に入り、全パスと記号を実ツリーに照合するようになった。毎コミットを止める14検査が一切記載されていなかったという、機械の規則と人が読む規則の分離こそ、繰り返す価値のある不都合な発見だった。","formats":{"gemtext":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/index.gmi","gopher":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/gophermap","html":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/","json":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/index.json","markdown":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/index.md","pdf":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/index.pdf"},"kind":"page","language":"ja","title":"文書を独自の静的検査で管理","url":"https://engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/","version":1}