# g3doc ## 概要 2014年の春、Googleの2人のテクニカルライターが社内エンジニアのドキュメンテーションに関する不満(社内wiki・Google Docs・イントラネット・Google Sitesへの散在による断片化とコンテキストスイッチのコスト)を調査したことをきっかけに開発した、社内エンジニアリングドキュメンテーション基盤。Markdownで書かれたドキュメントを関連コードと共にPiper(Googleのバージョン管理システム)内に保存し、コードベース内の場所を反映するURLでレンダリングする。(Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2.1) ## 設計原則 - コンテンツは編集しやすくソースでも楽に読めるものでなければならない。 - コンテンツは表示(レンダリング)から切り離す必要がある。 - Markdownを採用(GitHubが使う種類に追加のカスタマイズを施し、GoogleのレンダラーはHoedownに基づく)。DocBookのような別原則(ソースの読みやすさを犠牲にして多彩な出力を得る)を選ぶ余地もあるが、複雑さを持ち込む場合は現実のメリットによる正当化が必要とされる。 (Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2.2.2) ## 普及の経緯 初期プロトタイプはプレーンなMarkdownをレンダリングするだけの機能しかなく、テストチームの反応は「何かダサいな……でも発想は悪くないね」であった。g3docチームは基本機能を追加しつつ、他チームからの草の根の貢献(不足機能の自発的な構築)、他のエンジニアリングツール(コード検索・レビューツール・IDE)との小さな統合の積み重ね(チェックイン前のプレビュー機能等)、社内の著名なエンジニア・リーダーによる社内ソーシャルメディアでの推奨を通じて口コミで急速に普及した。導入開始から3年後(2017年10月)には、Google社内のエンジニアリングドキュメンテーションのほぼすべて(数千プロジェクト)がg3docと姉妹ツールのCompanyDoc(エンジニアリング指向を弱めた版)を使用するようになり、Googleは内部wikiを非推奨とした。導入後、Googleのエンジニア全員の約75%が毎月ドキュメントの変更をチェックインし、コードを含む変更リスト全体の約3分の1にドキュメントファイルが含まれるようになった。(Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2.1) g3docとEngPlayはバックエンドに共通サーバー(EngDoc)を使う。g3docは一般的なドキュメンテーションを意図しており、極めて高い信頼性を最優先とする[[EngPlay]]とは機能面で異なる。(Source: [[@2021__OReillyJapan__SREの探求 - Chapter 19 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合]] §19.2.1) ## 関連 - [[EngPlay]]: 手順書専用の姉妹プラットフォーム(共通バックエンドEngDoc) - [[Google]]: 開発・運用組織 - [[ドキュメンテーションのワークフロー統合]]: g3docが体現する原則の概念ページ ## 出典 - Ríona MacNamara、Shylaja Nukala 他, 「ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合」, David N. Blank-Edelman(編)『SREの探求』, オライリー・ジャパン, 2021, 19章 §19.2.1, §19.2.2.2.