10章 ドキュメンテーション
前文
2010年代後期のエンジニアリング関連ドキュメンテーションの状況は、1980年代後期のソフトウェアテストの状況に似ている
JUnitが1997年製なので当時の状況が全くわからない
「テスト駆動開発」付録Cの最古の記述はこのあたり
https://image.slidesharecdn.com/historyoftestingandcurrenttrends20190313-190405130314/75/-21-2048.jpg?cb=1666176871
https://image.slidesharecdn.com/historyoftestingandcurrenttrends20190313-190405130314/75/-23-2048.jpg?cb=1666176871
テストについて、この頃は「テストの恩恵(=品質)が認識され始めている」
ドキュメントについて、この頃は「ドキュメントの恩恵が認識され始めている」
10.1 何がドキュメンテーションとして適格か
10.2 何故ドキュメンテーションが必要なのか
しかしテストへの投資同様に、ドキュメンテーショ ンに行われる投資は、長期的には回収できる。
まず言い切っているのすごいなーと思った
同時に、短期的には回収できないというのを心得ておくと、ドキュメンテーションに対する心理的抵抗が減るよなと思った
後追いでドキュメントを作成してもらったりする機会があったがうまくいかず…(投資が)回収できるようなドキュメントが書けるようになるまでの道のりが大変っていうイメージがあります
結局のところ、ドキュメントが書かれるのはただ一度だけかもしれないが、後で読まれることは何百回、ことによると何千回もあることだろう
コードではよく聞くがドキュメントではあまり聞かない気がした。なんでだろう?
ドキュメントで恩恵にあった経験が少なくて読み返すようなドキュメントに出逢ったことがないとか?
仮説
コードはみんなが書いているがドキュメントを書く人はどう見積もってもその半分以下だから、単純に当事者が少ない
仮に誤っていても読む側が察しながら読んでくれる
エンジニアにとって、直接の納品物ではないので軽視されがち
逆に、ドキュメントが納品物となるコンサルでは品質を重視する
ドキュメンテーションは、以下のような質問に応えるのを手伝ってくれる
コミットログ、コードコメントもドキュメンテーション
設計書はこれとは別の場所に置くことになる?
「10.5.2. デザインドック」に記述があった。共同作業用のためGoogle Docsを使うことが多いとのこと
時代が早すぎた
JavaDocなんかは近いけど、設計意図を書くのは難しい
ドキュメンテーションを書くことは、APIが意味をなしているかを理解する最も確実な方法である
言葉にして初めて違和感が持てるのはあるあるなのでわかる
ラバーダックと似てる
どれだけの労力をドキュメンテーションに捧げるか決 めるという判断を、組織はある時点で行わなければならない。
この判断を特にしていない状態でふわふわとドキュメンテーション必要派と不要派がチーム内で争いを繰り広げることがあるような気がする
ドキュメンテーションは投資判断なので無尽蔵にお金がつっこめるわけではない
エンジニアにテクニカルライターになることを強制するのではなく、エンジニアにとってドキュメンテーションを書くことの負担を減らす方法について考えるべきである。
テクニカルライティングスキルを磨こう、みたいな側面でしか話を受けたことが自分はなかったので、この考え方は面白いしGoogleっぽいなあと思った
10.3 ドキュメンテーションはコードのようなものである
コード同様、ドキュメントにもまたオーナーがいるべきだ。オーナーを欠いたドキュメントは鮮度を失い保守が困難となる。
ドキュメンテーションって「チームみんなでやっていこう!」となっても人によって温度感はまちまちで結局ワークしないというのがよくあるんだよなーと思っていたけど、やっぱりこういうオーナーシップを持った存在が必要なんだなーと思った
Googleではwikiのメンテも自然に行われるような文化があるのかと思っていたが、オーナーシップが必要ということで意外だった
オーナーがいないとドキュメントが鮮度を失うというのは経験的には理解できるのだが、オーナーがいないとドキュメントの鮮度が落ちる原因はなんでだろう?DODや開発プロセスにドキュメント更新を入れておくだけだと、ドキュメントをメンテナンスしていこうとするフォースが足りないからだろうか?
ドキュメントの確認頻度が結局重要な気もする。オーナーシップを持つ人を決めたことで、ドキュメントの確認頻度が上がったとか
確認されたときに瑕疵があったら、オーナーシップを持つ人がいればそれがタスクになる
リリースノートを最初に書いてそれをスプリントゴールにして、ドキュメントを変更し、受け入れ条件を反映したテストを書き、その後に実装する、という流れならば確実に更新を反映することができる
PdM が1人で見られる物量ならでは
逆に、この運用ができるチームサイズが適切という考え方もできる
ソースコントロールフローの管理下に置かれる
レビューフローをコードと統一できて良い感じ
いくつか事例がみつかる
GitHubだと検索がイマイチ(ドキュメント用じゃないので当たり前)という問題がある
図や画像が使いたくなった時にどうするか…plantUMLを使うとかですかね。
しかし Google がスケールしてくると、wiki スタイルのアプローチの問題点が顕在化してきた。
逆にいうと、wikiスタイルでも小規模なチームなら成立しうるということなのかもと思った
Googleのドキュメント文化改善の過程を語っている動画らしい。後で見てみよう
https://www.youtube.com/watch?v=jJ93qzj-s7Q
10.4 対象読者を認識せよ
自分が最近身につけたドメイン知識が対象読者には掛けているのだということを、肝に銘じておこう
本当にそれ。略語とかドメイン特有の概念とかがぽんぽん出てきて当たり前のような感じで説明されると読むのがなかなかしんどい
ただ、このドキュメントを読む前につけないといけない知識があるな、という確認になるという点では意味はあるんだけれども
短いドキュメントを書くには、もっと長いドキュメント(全情報を入れて)を書き、それから編集工程を通して、重複した情報を可能な限り取り除くことが多い。これは退屈なように聞こえるかもしれないが、そのコストはそのドキュメンテーションの全読者に負担されることを心に留めておいてほしい
前半部分を読んだ時、それはさすがに厳しいなあ...と思ったけど、後半の文章を見て、実践しなきゃなあと思った
リファクタリングの要領で、コードがきれいな人はドキュメントもきれいなのでは?
肌感: そうじゃない気がする
コンピュータがコードを実行するのと人間がドキュメントを読むのとは処理の過程が違う
対象読者の区別で他に重要なものは、ユーザーがどのようにドキュメントに出会うかに基づいている。
読者の知識レベルはなんとなく書くときに考えることがあったけど、ドキュメントとの出会い方について考えることはなかったので自分にない区別の付け方でおもしろいなと思った
10.5 ドキュメンテーションの類型
関数コメント上での様々な形式の定型文を要求するのもあるが、Googleではそれらは必要であると考えられてはいない
やりがちだったが、たしかに自然な形で書かれている方が全然読みやすいし、定型文にすると冗長になるなあ
(ランディングページは)他ページへのリンクのみを含めるようにする
これをやるということは、必要な情報を定義し、それに従ってドキュメントを書いた上で保守するということ
逆に、ここに含まれていないものは古い情報(アーカイブすべき)か個人のメモ(眉に唾をつけて読め)である、と定義される
上にもあるけど、オーナーシップを持つ人が必要だと暗に言っている
しかし重要なのは、異なった類型を知ること、そして類型を混同しないことである
欲しい情報をばんばん一つのドキュメントに書きがちなので刺さった。。
今日ちょうど仕事で「オブジェクト分割がなぜ必要なのか」という話をしていて、ドキュメントが目的ごとに分割されるべきという話と似ていると思った
スコープが小さいので整合性を保ちやすい
名前空間が自然に切られるので変数名を一意に特定しやすい
処理の目的外利用がされにくい
10.6 ドキュメンテーションのレビュー
通常は、ドキュメンテーションもまたレビューを要する(とはいえ、この点はコードレビューのように満場一致で受容されているわけではない)
さらっと書いてあるけど、コードレビューは有意義だけどドキュメントレビューは有意義でないと考えている人たちの意見はぜひ聞いてみたい
理由が全く語られていない
コードレビューのような厳密なプロセスを適用する必要はない、という意味?
ツールが貧弱なので品質の担保が難しい?
ソフトウェア工学では盛んに研究されているが、メソドロジーが確立していない
AIが解決する?
コードとドキュメントを食わせて、嘘をついていないか調べる
10.7 ドキュメンテーション哲学
WHYはそのドキュメントの目的を確立する
これを定義するのが片手間には難しいから、着手のハードルが上がってなかなかドキュメントが書かれないのでは?とおもった
やはり強力なリーダーシップが必要
古いドキュメントも問題を起こす可能性がある
「ドキュメントが信用されなくなる」「信用されてないドキュメントはどこから手をつけて良いかわからないので、メンテナンスもされない」という致命的な欠点になりうるので、この項はもう少し扱いが大きくても良いと思った
Googleではそんなことは起きてないんだろうけども
10.8 テクニカルライターが必要なのはどんなときか
ソフトウェアエンジニアリング分野のテクニカルライター
どんなキャリアの人がなるんだろうか
日本だったらSoftware Design の記者の方とか?
テクニカルライターは限られたリソースである。したがってテクニカルライターは、ソフトウェアエンジニアが標準の職務の一部として行う必要のないタスクに通常は専念すべきだ
チームトポロジーでいうところの プラットフォームチーム
10.9 結論
全体的に、個々人の意識や頑張りの話に止まりがちなところはGoogleっぽくないし、Googleでドキュメントがまだ第一級の扱いを受けていない理由なんだろうなあと感じた
前文で言ってた「1980年代後半のソフトウェアテスト」という例えがまさにそれ
10.10 要約
みんなからのコメント
Googleにしかできないとしたら、それはなぜか?
優先度の低さ。ドキュメントが重要であることは間違いないものの、ソースコードを書くことやテストコードに比較すると、プロダクトに必要不可欠なもの(ないとリリースができないもの)ではない。
メンテナンスコストの高さ。プロダクトの採算を取ろうとすると、メンテナンスコストが高いドキュメントにはメンテナンスコストをかけられない
ただ、プロダクトの採算を取ろうとするとドキュメントをメンテナンスする余裕がないという時点で、プロダクトがいけていない説はある
そもそも「作って終わり」の開発だと予算がつかない
品質を検査し保持する難しさ
コードにはある「テストが通っている」という最低基準が作りにくい
レビューを通しても、変更されるたびに全体を通したレビューを行うのは高コスト
現場でどこまでできているか?
ドキュメントがないので作ろうとしているがなかなかうまくいかない。コードを元に作ってしまうことで、コードとかなり似通ったドキュメントが出来上がってきてしまい、それならコードを確認しますってなってしまう(自分もそうですが…)
この本があるのになぜ実践する企業はすくないのか?
品質が低いドキュメントに対して問題意識を持っている人はいるものの、それ以上に強い問題意識がある事象を多くの企業では抱えていそうだから?
誰かにオーナーシップを持たせるとしたら大抵の企業ではEMやPdMになり、忙殺される
ドキュメンテーションは方法論が確立されておらず、定番ツールもWiki程度しかない
定番ツールがない=運用を定着させにくい
それの乗り越え方はなにか?
リーダーシップを持つ人がやることとやらないことを決めて、運用に乗せるまでやりきる
ステップを小さくするとしたらどうできそうか?
まずは議事録など普段書く機会が多いドキュメントを10.7のドキュメンテーション哲学を意識して書いてみる