ドキュメンテーションのワークフロー統合

# ドキュメンテーションのワークフロー統合 Navigation: [[index]] | [[concepts/_index]] ## 定義ドキュメンテーションのワークフロー統合とは、ドキュメンテーションをコードとは切り離された別作業として後回しにするのではなく、コードと同じソース管理システム・レビュープロセス・ツールチェーンの中で扱うことで、作成・保守のコストを引き下げ品質を向上させるアプローチを指す。この発想の背景には、ソフトウェアテストがかつて(10年前の時点で)アドホックで標準化されていなかったが、現在ではエンジニアリングのプロセスやツール群と緊密に統合され、テストされていないコードが本番へプッシュされることはありえない状態になったという先例がある。ドキュメンテーションについても同じ変化を起こせるという主張が本概念の出発点である。この統合の判定には、ドキュメントがどのようにあるべきかを記述する構造品質(structural quality)と、目的にかなうかどうかを記述する機能品質(functional quality)という2軸の品質フレームワークが用いられ、機能品質のほうが常に重要性が高いとされる。(Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.1, §19.2) ## Googleの実装(g3doc / EngPlay)が示す3原則 - **可能な場合、ドキュメンテーションは関連コードと一緒にソース管理システムに置く**: SWEとSREがコードの作成・編集と同じツールでドキュメントを編集・レビュー・チェックインできるようになり、リンター/フォーマッタ・リンク切れ検出・ライブコード埋め込みといった、ドキュメント管理からトイルを取り除く機能が実現する。 - **ニーズに応える最もシンプルなマークアップ言語を選ぶ**: 「コンテンツは編集しやすくソースで読めるものでなければならない」「コンテンツは表示から切り離す必要がある」という2原則からMarkdownが選ばれた。要件次第では別の原則(DocBookのような多彩な出力を優先する原則)もありうるが、複雑さを持ち込む場合は現実のメリットによる正当化が必要になる。 - **統合が導入の鍵**: コードレビューツールへのプレビュー機能の追加、コード検索・閲覧ツールからのレンダリング表示など、個々には小さな統合の積み重ねが摩擦を減らし、プラットフォームの導入を口コミで加速させる。 (Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2.2) ## 横断的知見 - 単一ソース([[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]])からの創設のため、複数ソースを突き合わせた横断的知見は今後の ingest で育てる。ただし同じ書籍内の隣接章との接続は以下のとおり観察できる。 - **19章の「ドキュメントをワークフローへ統合する」主張と、20章のアクティブラーニング実践は、日常業務の中に学習・文書更新のトリガーを埋め込むという同じ設計思想を共有する**: 19章はドキュメンテーションを独立した別作業ではなく通常のエンジニアリングワークフロー(コードレビュー・チェックイン前チェック)に組み込むことでコストを下げると主張する。一方 [[@2021__OReillyJapan__SREの探求 - Chapter 20 アクティブなティーチングとラーニング]] は、プロダクションミーティングで新任エンジニアが理解できなかった点をリスト化しメンターが説明する実践を「ドキュメンテーションを最新化する機会にもなる」と明示的に位置づけている。両章はそれぞれ別の主目的(ドキュメント統合/能動的学習)を持ちながら、「既存の日常業務(コードレビュー、ミーティング)に新しい価値(ドキュメント更新、学習)を便乗させる」という同型の設計思想に収束している。(Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2, [[@2021__OReillyJapan__SREの探求 - Chapter 20 アクティブなティーチングとラーニング]] §20.3.1) ## 未解決の問い - g3doc/EngPlayのような「コードベースに埋め込まれたURL」でドキュメントをレンダリングする方式は、マイクロサービス化が進みコードベースが多数の小さなリポジトリに分散した組織(Googleのmonorepoとは対照的な環境)でも同様の発見可能性(discoverability)を維持できるか。 - 「機能要件を満たし明確に伝わっていれば完全でなくてよい」という現実的な品質基準("ベター>ベスト")は、規制対応文書やコンプライアンス文書のように完全性そのものが要件になるドキュメント種別にも適用できるか、それとも例外を設けるべきか。 - コードレビューでドキュメント更新を求める際の判断基準(「行動を変える必要があるか」)は、レビューアの主観に依存する。この基準を自動化・定量化する試みは他ソースに存在するか。 - ドキュメンテーションの機能品質データ(計測可能な成功・ユーザー行動・センチメント)は、[[開発者生産性]] の SPACE フレームワークのどの次元と対応づけられるか。本概念のソース群にはまだ明示的な接続がない。 ## 関連 - 概念: [[トイル]](ドキュメント管理からトイルを取り除く機能) / [[開発者生産性]](コンテキストスイッチのコスト) / [[技術的負債]](不要なドキュメントの負債化) / [[ダッシュボードとランブックの運用]](手順書というドキュメント種別の運用論) / [[SRE文化]] / [[アクティブラーニング]](日常業務への便乗という設計思想の共有) - 実体: [[Google]] / [[Microsoft]] / [[Ríona MacNamara]] / [[Shylaja Nukala]] / [[g3doc]] / [[EngPlay]] - ソース: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] / [[@2021__OReillyJapan__SREの探求 - Chapter 20 アクティブなティーチングとラーニング]] ## 出典 - [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]]