# 文書を独自の静的検査で管理

文書に、引き下げのみ可能なファイル別行数上限、目次要件、実在パス検査を設けた。完了扱いの9計画中6計画に未完了項目があり、コミットを制御する14タスクがどの文書にも記載されていないことを検出した。

8月 2026

状況. 品質、デザイン、アクセシビリティ、印刷、メタデータ、翻訳、gitを26文書の指示で管理していた。指示は長くなり、コードからずれ、移動したファイルを参照し、一定の長さで読まれなくなる。読まれない規則は規則として働かない。

課題. 助言でなく失敗する上限を持つ静的検査を設け、文書もコードと同じように扱う必要があった。

行動. 8つの機械的な方針を設けた。文書長の絶対上限と警告する目安、縮むだけで戻らないファイル別行数予算、大きさに応じた全体目次・節目次、主題の担当文書を定める配置規則、リンク妥当性、主張とチェック欄が一致する計画の正直さ、コミットを制御する全タスクの文書記載、記したパスとコード記号の実在検査だった。初回で、未完了欄付きの完了6計画、どこにも記載のない14タスク、リンク切れ3件、孤立文書1件、5文書にまたがる死んだパス3件を検出し、必要性を示した。その後、この仕事の説明を開発文書へ加えると上限に達し、作成者自身を拒否して別文書が生まれた。意図どおりの働きだった。

結果. 計約2,666実効行の26文書が、増やせない予算下に入り、全パスと記号を実ツリーに照合するようになった。毎コミットを止める14検査が一切記載されていなかったという、機械の規則と人が読む規則の分離こそ、繰り返す価値のある不都合な発見だった。

役割: テクニカルプロダクトマネージャー
=> /ja/categories/automation/ カテゴリー: 自動化・CI/CD
=> /ja/categories/testing/ カテゴリー: テスト・品質保証
=> /ja/categories/python/ カテゴリー: Python
=> /ja/categories/technical-leadership/ カテゴリー: 技術面の統率
=> /ja/categories/project-management/ カテゴリー: プロジェクト管理
=> /ja/categories/documentation/ カテゴリー: 文書作成
=> /ja/services/technical-leadership/ サービス: 技術面の統率・コンサルティング
=> /ja/services/project-management/ サービス: プロジェクト管理（アジャイル）
=> /ja/services/technical-documentation/ サービス: 技術文書の作成

=> https://advisory.engineer.company/ja/portfolio/put-the-documentation-under-its-own-linter/ このページのウェブ版
