前回まででテストについてを読みきった。今回は引き続き
の第3部 プロセス 10章 ドキュメンテーション、を読んでいき、学んだことや考えたことや印象的なことを記していく。
10章 ドキュメンテーション
エンジニアは皆、自身のキャリアのどこかの時点で、ドキュメンテーションの質、量、あるいは完全な欠如についての不満を表明したことがあるものだ。そして、Googleのソフトウェアエンジニアもその例外ではない。
やっぱりそうか、という感じ。
Googleで最も成功を収めている取り組みは、ドキュメンテーションをコードのように扱うとともに、伝統的なエンジニアリングのワークフローへ組み込むというものであり、エンジニアが単純なドキュメントを書いて保守するのを楽にしている。
バージョン管理、プルリクエスト、みたいな感じ？
10.1 何がドキュメンテーションとして適格か
つまり、独立したドキュメントだけでなく、コードのコメントも含まれる(実際Googleのエンジニアを書くドキュメンテーションの大半は、コードのコメントの形をとって現れる)。
独立したドキュメントの整備の仕方に、自分は興味がある。
10.2 何故ドキュメンテーションが必要なのか
(いずれ見ていくように)すぐにプログラマーの利益になるテストと違い、ドキュメンテーションは通常、より多くの労力が前もって必要で、後になるまで作者に明確な利益をもたらさない。しかしテストへの投資同様に、ドキュメンテーションに行われる投資は、長期的には回収できる。
すぐには結果は出ないが、大きな良い結果が後から得られる。
どれだけの労力をドキュメンテーションに捧げるか決めると言う判断を、組織はある時点で行わなければならない。
ドキュメンテーションの恩恵を得るためには、個々人ではなく、最終的には組織で動く必要がある。
GoogleのC++スタイルガイドには「読者に向けて最適化せよ(https://oreil.ly/zCsPc)」という箴言(しんげん)が記されている。
箴言(しんげん)がわからなかったが、アドバイス、的な意味だろう。雑に調べるとやっぱり「戒めの言葉や教訓、格言などを意味する言葉」とあった。
10.3 ドキュメンテーションはコードのようなものである
ドキューメンテーションを書くことは、コードを書くことと大して変わらない。プログラミング言語同様に、ドキュメンテーションにはルールがあり、特定の構文があり、スタイルについての決定があるのであって、コード内でそれらが持つ目的に似た目的をドキュメンテーション内で果たしていることが多い。
コード同様、ドキュメントにもまたオーナーがいるべきだ。オーナーを欠いたドキュメントは鮮度を失い保守が困難となる。
ログを残すような感覚でドキュメントを書く事は難しくないが、それらを選択し、まとめ、整理する、という事はオーナーや当事者意識がいないとなかなか難しい。
Googleでは「go/リンク」が広く使われている（3章参照）おかげで、このプロセスが簡単になっている。。go/リンク直行先のドキュメントがカノニカルな「頼できる情報源」となることが多い。
ドキュメントの中に別のドキュメント等で飛ぶためのリンクは重要。
ドキュメンテーションをソフトウェア開発で必要なタスク「の1つ」として扱うエンジニアが増えると、文章を書いておくという先行コストに対してエンジニアが不愉快に感じることが減り、エンジニアが回収できる長期的利益が増えることになる。その上で、ドキュメンテーションのタスクをさらに簡単にできれば、そうした先行コストは低下する。
ドキュメントを書くのは、当たり前のこととしておくのがベター。
ケーススタディー : GoogleのWiki
Google内では最初ウィキを使っていたが、すぐにウィキスタイルだと問題になってきた。
印象深かったのがドキュメントを修正する人とドキュメントを利用するとか別と言う事。特に修正する者にとっては、修正した後はそのドキュメントを参照することは少なく必要なくなる、という状況が生まれる点には思い当たる節がある。
ドキュメンテーションをソースコントロール下に移すのは、最初は大いに論争の的になった。 多くのエンジニアが、情報の自由の岩としてのGooWikiを廃止すると、ドキュメンテーション作成の障壁（レビューが要ること、ドキュメントのオーナーが要ること、等）が高くなるせいでドキュメンテーションの品質が劣化すると確信していた。しかしそうはならなかった。ドキュメントの品質は上がったのだ。
10.4 対象読者を認識せよ
代わりに、ドキュメントを書き始める前に、（正式に、あるいは略式に）自分のドキュメントが満足させる必要のある対象読者を特定するべきだ。
これの前段に、今の自分のためだけにドキュメントを書いてしまいがちということが書かれてあった。自分のことを思い返してみると、1年後2年後に忘れたときの自分のためにドキュメントを書くことにしている。このようにして書いたブログが後々役に立ったり、仕事でも周りの役に立ったりしているので、想定読者が今の自分なのか将来の自分なのかは大きな差なのだ、と思う。
優れたドキュメンテーションというものは、洗練されていたり「完璧」であったりする必要はない。
私が読者として、あくまで自分を想定しているのは、自分にとって確保が気が楽だからだ。気楽にある程度雑に完璧を目指さずに書いていく。
10.4.1 対象読者の類型
対象読者のタイプやグループとして、詳しい詳しくないか、何がしたいか何がしたくないのか、の2種を意識すると良さそう。
特に何がしたいかで言えば、
捜索者、自分の欲しいものがわかっているタイプがあり、捜索者向け文章は一貫性を大事にしたほうが良い。もう一つのタイプは遭遇者で、自分が何を欲しいかわかっていないかもしれないタイプ。この場合は明確性が大事。
自分を振り返ってみると、実装の時によくわからなくて、Googleで調べるみたいな場合は、捜索者としてドキュメントを探しに行っている。このことから、自分が求めているドキュメントや自分が書くドキュメントは捜索者向けの比率が大きそうと思った。
さて、本書に書いてある秘訣としては、異なる対象読者グループに、できるだけ広く当てはまるように書く、というのがあった。また、プラス、ドキュメントを短く保つのが役に立つと発見したともあった。そうだなと思う。
また、「短く書け」に関わる次の文章は、へー、そうなんだ、知らなかった、と思った。
Blaise Pascalがかって述べたように、「もし私にもっと時間があるなら、あなたにもっと短い手紙を書いただろう」というわけだ。
10.5 ドキュメンテーションの類型
しかし重要なのは、異なった類型を知ること、そして類型を混同しないことである。一般に、ドキュメントは唯一無二の目的を持ち、それを貫き通すべきだ。APIが1つのことをやり、それをうまくやるべきであるのと全く同様に、1つのドキュメント内で複数のことをやろうとするのは避けるべきだ。
仕事で「このページについて」という見出しをウィキの最初に設けている。これはきっと類型、種類、を明確にするためのガイドの役割も果たしていると思う。書く時間が取れないな、と思ったら、このドキュメントはこういう種類のものです、ということを一言書くと機能しやすいのではないかと思った。
10.5.1 リファレンスドキュメンテーション
リファレンスドキュメンテーションという名称で我々が指しているのは、コードベース内でコードの利用方法をドキュメント化するもの全てである。
要するにプログラムコードにつけるJavaドックやPHPドックのようなクラスコメントやメソッドコメント。
10.5.2 デザインドック
ここ5年位でデザインドックという言葉を知り、耳にするようになった。が、どういったものなのか全くわからなかった。あまり紙面は充てられていないが、どういうものであるかを、理解が多少深まった。
実作業の着手前にデザインドキュメントの承認が求められる。
設計の議論が、あらゆるコードが書かれる前に一種のコードレビューの役目を果たしている。
Googleでのカノニカルなデザインドキュメント用テンプレートは、設計の側面のうち、セキュリティ上の影響、国際化、ストレージ要件、プライバシーについての懸念点、等の考慮をエンジニアに求める。
優れたデザインドキュメントは、扱う対象に設計のゴールと設計の実装戦略を含み、鍵となる設計上の決定を、個々のトレードオフに重点を置いた形で提案するはずだ。
優れたデザインドキュメントはさらに、一旦承認されると、履歴の記録として働くだけでなく、そのプロジェクトがそのゴールの達成に成功したかを計測する尺度にもなる
10.5.3 チュートリアル
メモ帳か、何か他のメモを取る手段を用意し、ドメイン知識や特別な構成上の制約を前提とせずに、途中でやらなければならないことを全部書き留めるべきだ。それを済ませたら、そのプロセス中にどんな間違いをしたか、そして何故間違ったかが、おそらくわかることになるだろう。そこから自分の手順を編集していくと、さらに簡潔にまとまったチュートリアルが得られる。重要なのは、途中でやらなければならないことの全てを書くということだ。
そのチュートリアルが重視しているのがユーザーである場合（例えば外部開発者用ドキュメンテーション向けの場合）、ユーザーが自分で試みる必要のある各行動に番号を付けなければならない。そのようなユーザーの行動に応えてシステムが実行する可能性のある活動には、番号を付けてはならない。実行時の手順に番号を明示的に振ることは、決定的に重要だ。
読書がやることだけを漏らさず書く。番号を明示的に振る。実施するとこうなるはずといったいわゆる副作用的な結果の言及は書くのは構わないが番号を振らない。
10.5.4 概念的ドキュメンテーション
概念的ドキュメンテーションの例としては、普及しているAPIのライブラリーの概観、サーバー内のデータのライフサイクルを説明するドキュメント等がある。概念的ドキュメントはほとんどの場合、リファレンスのドキュメンテーションのセットを置き換えるのではなく、強化することが意図されている。
概念的ドキュメントの主は、理解を分け与えることだ。
「概念」ドキュメントは、書くのが最も難しいドキュメンテーション形式である。
概念的ドキュメントを書く際にエンジニアは、概念的ドキュメントを配置するためのカノニカルな場所がないので、ソースコード内に直接埋め込むことができないという問題によく直面する。
概念的という名前の通り、抽象的な、俯瞰的な視点のドキュメント。 明確性が最大の目的で、完全性はリファレンスドキュメンテーションがよりふさわしい。
往々にしてAPIなど同士の関係性を明確にするドキュメントなので、ドキュメントを配置する場所が決まっていない。
10.5.5 ランディングページ
要は、ランディングページが必ず目的を明確に特定しているようにし、それからさらなる情報を得るための他ページへのリンクのみを含めるようにするのだ。もしランディングページ上で交通整理の警官以上のことをやっているものが何かあったら、そのランディングページは本来の仕事をしていない。
大半のうまく設定されていないランディングページは、2つの別の目的に従事している。つまり、自分の製品かAPIのユーザーである者向けの「頼みの網」のページか、チームのホームページだ。 ページは二君に仕えるようにすべきでなく、さもなければ混乱させるものになることだろう。
自分の仕事では、ウィキにおいては顧客やプロジェクトのトップページがこれにあたる。緊急事態時にのみ必要な短い情報と、後はリンク、という構成ページ内容になっている。昔はもっとごちゃごちゃといろいろ載せていたのだが、整理していったら、この形に落ち着いた。まだ改善の余地はあると思うのだが、本書のランディングページがまさに該当すると思った。
10.6 ドキュメンテーションのレビュー
- 正確性のための技術的レビュー。このレビューはたいていの場合、チームの別のメンバーであることが多い、扱われる内容についての専門家によって実施される。これがコードレビュー自体の一部となることがよくある。
- 明確性のための対象読者レビュー。これはたいていの場合、その領域に親しんでいない者によって行われる。それはチームの新人か、APIの利用者かもしれない。
- 一貫性のための作文法レビュー。これは、テクニカルライターか、志願者によることが多い。
ドキュメンテーションのレビューの時にの重要な3つの観点は、正確性、明確性、一貫性。どれを念頭に置いてレビューをするのかレビューしてほしいのか、を意識すると良さそう
重要なのは、ドキュメンテーションがエンジニアリングのワークフローに結びついているならば、ドキュメンテーションは時間の経過とともに改善されていく場合が多いということである。
ドキュメントレビューを日常のワークフローに結びつける方法の1つとして、ウィキでならば間違いや改善があったらばすぐ直してしまってオッケーとする、というのが思いついた。この場合、レビュアーが自分自身になってしまうが、それは許容するのがベストではないがまだマシという位置付けとなる。
10.7 ドキュメンテーション哲学
技術的な文章の書き方のベストプラクティス、技術的情報を書くことを容易にするための情報。以上が次節で述べられる。
10.7.1 誰が、何を、いつ、どこで、何故
どんなドキュメントでもHOW以外の質問には最初の2つの段落内で対処するよう努めるべきだ。
- WHOは前に論じた。それは対象読者だ。 …略…
- WHATは、そのドキュメントの目的を特定する。 …略…
- WHENは、そのドキュメントが作成されたとき、レビューされたとき、更新された時を特定する。 …略…
- WHEREもまた暗に示されている場合が多いが、そのドキュメントがどこに存在すべきかを決定しなければならない。 …略…
- WHYはそのドキュメントの目的を確立する。そのドキュメントの読後に覚えておくことが期待される教訓を教訓を要約しなければならない。 …略…
10.7.2 始まり、中盤、終わり
ドキュメントが複数の説に分かれる、始まり、中盤、終わり、に分かれる事は恐れなくてよい。この恐れは冗長性をエンジニアは嫌うということから来ており、それはもっともなのだが、ドキュメントにおいては冗長性が有益なことがままある。最初の節でまとめを言い、次の節でそれを掘り下げていき、としている間に同じ言葉や同じ説明を何回か繰り返すことはよくあるがそれは問題ない。他のエンジニアの記憶の助けや、理解の助けにするため、というのが目的だからだ。大事なことなので2回言いました、というやつ。
10.7.3 優れたドキュメンテーションの特徴的要素
優れたドキュメンテーションには一般に3つの簡面がある。完会性、正確性、明確性だ。
全てを満たすのは難しく、また現実的ではない場合が多いので↓
各場合で、「優れたドキュメント」はその意図された役目をこなしているドキュメントとして定義される。
その実現方法は↓
どのようにすればドキュメントの品質を素早く改善できるだろうか。対象読者の必要とするものに専念すればよいのだ。しばしば、より少ないことがより良い結果を生む（less is more）。
10.7.4 ドキュメントを廃止する
Googleでは、しばしばドキュメンテーションに「鮮度日付（freshness date）」を付加する。そうしたドキュメントにはドキュメントが最後にレビューされた日時が付記してあり、そのドキュメンテーション集のメタデータ（metadata：データに関するデータ）が、そのドキュメントに例えば3 か月間手がつけられていない場合に、eメールでリマインダー（reminder：忘れないように思い出させる通知）を送ることになる。
廃止というよりかは、鮮度の維持。古くなってきたらチェックして修正すべきかどうか判断する。そのやり方、サイクルについて記しているとの印象を受けた。
10.8 テクニカルライターが必要なのはどんなときか
通常、APIの境界を越えるドキュメントを書くような場合がそれにあたる。Fooプロジェクトにとっては、Fooプロジェクトがどんなドキュメンテーションを必要としているかは明確にわかるかもしれないが、Barプロジェクトが必要なものについては、おそらくそれほど明確に見当はつかない。テクニカルライターは、その領域に馴染みのない者の役目を務めることができるようであるとなお良い。実際、テクニカルライターの持つ決定的に重要な役割として、プロジェクトの用途に関してチームが持つ思い込みを疑ってかかるという役割がある。
自分たちのチーム、自分たちのプロジェクト、に関するドキュメントが全く問題なく書ける。よって、ドキュメントを書く専用のテクニカルライターが必要なのは、プロジェクトとプロジェクトの間、システムとシステムの間、越境、の時に必要になってくる、効果を発揮する、と考えると良さそう。
10.9 結論
必然的に、ドキュメントは主観的なものとなる。そしてドキュメントの品質は、書き手ではなく読者によって測られるのであり、それも書かれるのと同時ではなくかなり後の時点で測られることがしばしばある。
プログラムコード・ユニットテストとドキュメントの違い。特にドキュメントの評価（ユニットテスト的なもの）はユニットテストのように即座ではなく、かなり後で評価されることがしばしばという点が印象的。
ドキュメンテーションの現状にお手上げ状態になるのではなく、品質の高いドキュメンテーションの生産は、自分たちの仕事の一部であり、長い目で見ると時間と労力の節約になるのだと悟る必要がある。
ドキュメンテーションを扱っていく当事者意識が何よりも必要。
10.10 要約
- ドキュメンテーションは、長期的かつスケールの観点から見て、極めて重要である。
- ドキュメンテーションの変更は、既存の開発者ワークフローを活用すべきである。
- ドキュメントは1つの目的に専念したものにとどめておかなければならない。
- ドキュメンテーションは対象読者に向けて書くべきであり、自分自身のために書くべきではない。
おわりに
2025年4月17日(木)読み終わった。読み始めた日付を記し忘れていたが、3月23日に前の本を読書感想文を投稿したので大体25日かかったことになる。
特に得られたと思ったのは、ドキュメンテーションの類型、つまり、種類、タイプ、を整理できた事だ。
- リファレンスドキュメンテーション
- デザインドック
- チュートリアル
- 概念的ドキュメンテーション
- ランディングページ
自分がこれからドキュメントを書く前、書いてる時、書き終わった後、に自分は今どの類型のドキュメントを書いているかを意識したり、見直したりすると、もっと質が上がるのではないかと思った。
以上です。