Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス

10章ドキュメンテーション

Tom Manshreck 著

Riona MacNamara 編

　コードを書き、使い、保守することについて大半のエンジニアが持つ不平のうち、並ぶものなく際立ってよくある不満点は、品質の高いドキュメンテーションの欠如である。「このメソッドの副作用は何か」「手順3の後でエラーが出た」「この頭字語は何を意味するのか」「このドキュメントは最新か」エンジニアは皆、自身のキャリアのどこかの時点で、ドキュメンテーションの質、量、あるいは完全な欠如についての不満を表明したことがあるものだ。そして、Googleのソフトウェアエンジニアもその例外ではない。

　テクニカルライターやプロジェクトマネージャーがいれば助けになるかもしれないが、ドキュメンテーションの大半は、常にソフトウェアエンジニアが自分たち自身で書かなければならないだろう。したがってエンジニアは、ドキュメンテーションを効果的に書くという目的のために、適正なツールとインセンティブとを必要としている。エンジニアが質の高いドキュメンテーションをより楽に書けるようにするための鍵となるのは、組織とともにスケールし既存ワークフローと調和するようなプロセスとツールの導入である。

　全体的に見て、2010年代後期のエンジニアリング関連ドキュメンテーションの状況は、1980年代後期のソフトウェアテストの状況に似ている。ドキュメンテーションを改善するのにさらなる取り組みが行われるべきであると皆が認識しているものの、ドキュメンテーションの決定的に重要な恩恵に対して、組織レベルでの認識はまだないというわけだ。ゆっくりとではあるが、その状況は変化している。Googleで最も成功を収めている取り組みは、ドキュメンテーションを ...