技術ドキュメントは、いつも決まった、そして予測のつくかたちで失敗します。誰かが二週間ほどの落ち着いた時期に大量に書き上げ、そのあいだにシステムのほうが変わり、誰も更新せず、一年も経てば、その文書は自信たっぷりに間違ったことを述べている状態になります。そこから先は、何もないよりも悪い状態です。書いてあることを信じた読み手が、すでに成り立たなくなった情報にもとづいて手を動かしてしまうからです。
これに対するよくある反応は、もっと書こうという号令です。ところがそれは同じ失敗を早めるだけで終わります。役に立つ反応は、書く量を減らし、そのうえで何を書くのかを選ぶことです。ここでの制約は書く手間ではありません。書いたあとに保守し続ける手間のほうです。文書は書き上がったその瞬間から、現実に追い越されていきます。
ある文書を存在させるべきかどうかを見分ける、唯一長持ちする基準： それが間違いになったとき、誰かが気づくか。デプロイ手順書は日常的に使われるので、誤りはすぐに表へ出てきます。ある一つのサブシステムを二十ページかけて説明した文書は一度しか読まれず、その誤りは十八か月後、誰かがそれを頼りに手を動かしたときになって初めて表へ出てきます。誰も実際には使わない文書は、静かに腐っていきます。書かずに済ませるべきなのは、まさにそういう文書です。
なぜ古びるのか
仕組みは三つあり、そのうち怠慢と呼べるものは一つだけです。
ドキュメントは、それが説明している対象から離れた場所に置かれています。 コードを変えることは、ウィキのページを変えることではありません。両者を揃えておけるかどうかは、誰かがそれを思い出すかどうかだけにかかっています。その思い出しは確実に失敗しますし、文書がコードから遠いところに座っているほど、失敗は早く訪れます。別のツール、別の権限、別の画面に置かれているという、ただそれだけの距離が効いてきます。
意図ではなく実装のほうを書いてしまっています。 ある部品がいま現在どう動いているのかを説明した文書は、リファクタリングのたびに無効になります。その部品がなぜ存在し、どんな制約を満たすために置かれているのかを説明した文書は生き残ります。理由が変わる頻度は、コードが変わる頻度よりずっと低いからです。
誰も持ち主になっていません。 全員のものであるドキュメントは、誰のものでもありません。その正確さが特定の誰かの担当課題になる瞬間が、最後まで訪れないのです。
打ち手は原因からそのまま導けます。コードの近くに置くこと、仕組みではなく意図を書くこと、そして文書ごとに名前の付いた持ち主と、それが実際に使われる機会の両方を用意することです。
保守する価値のある技術ドキュメント
四つの文書で価値のほとんどが取れます。それ以外は、存在してよい理由を自分で示す必要があります。
動かせるところまで連れて行く README。 これが何なのか、どう用意するのか、テストはどう走らせるのか、どう配ればよいのか。絶えず使われるので、誤りはすぐに表面化します。どのリポジトリでも投じた手間に対する見返りがいちばん大きい文書であり、同時に、誰も手を入れていないプロジェクトのひな型のまま放置されていることがいちばん多い文書でもあります。
アーキテクチャの俯瞰。 大きな部品は何で、それらはどう通信し、なぜ分かれているのか。細部ではなく形を説明する、一ページの文章と一枚の図があれば足ります。めったに変わらないうえに、これがなければ新しく入った人がすべてを読んで自力で組み立て直すことになる問いに、先回りして答えてくれます。
決定記録。 ある決定と、検討した代替案と、そう選んだ理由を短く書き留めたものです。業界では通常アーキテクチャ決定記録、略して ADR と呼ばれます。書き足すだけで、あとから更新する必要は生じません。そしていちばん高くつく種類のやり直し、つまり、いちど決着した論点を、決着させた制約を誰も覚えていないまま下手に蒸し返す作業を防いでくれます。
壊れるもののためのランブック。 ランブックとは障害対応の手順書のことで、実際に起きた障害をどう切り分け、どう直すのかを書いたものです。事故のあと、記憶がまだ新しいうちに書き、次の事故のときに試されます。まだ誰もたどったことのないランブックは、下書きにすぎません。
この四つのどれも、コードがどう動くかを説明していない点に注目してください。それはコード自身の仕事であり、それを言葉でなぞった文章は、いずれ最初の一つと食い違う二つ目の正解になってしまいます。
疲れていて急いでいる人に向けて書く
技術ドキュメントの大半は、圧力のかかった状態で読まれます。読み手ははっきりした一つの疑問を抱えていて、それも多くの場合は業務時間の外です。ゆっくり読める人ではなく、その読み手に向けて書いてください。
先に答え、あとから説明。 午前二時にあなたのランブックを読んでいる人に必要なのは、まずコマンドで、理由はそのあとです。答えより先に背景を置く構成は、書き手には都合がよく、ほかの誰にとっても都合が悪いものです。
具体的に書く。 本物のコマンド、本物のパス、本物の例の値。「適切な環境変数を設定してください」は指示ではありません。指示についての説明にすぎません。読み手はその適切が何を指すのかを知りたくて、そのページを開いています。
何がうまくいかないかを書く。 失敗のしかたと、それがどう見えるか。これはしばしばページの中でいちばん価値のある部分になります。読み手がまさにいま体験しているのが、それだからです。
正しいままでいられる程度に短く保つ。 文が一つ増えるたびに、保守の負債も一つ増えます。よくある場合だけを扱い、自分の守備範囲の外を正直に認める一ページは、すべてを扱ったうえで三か所間違っている文書に勝ちます。
検索や取得のしくみに引用されやすいページを作る規律は、そのまま、疲れきった同僚が使えるページを作る規律でもあります。公開する文章について順位は取れているのに引用されない理由で述べているのも、まさにこの点です。
生かし続ける方法
リポジトリの中に置く。 コードと一緒に移動する文書は、コードと同じレビューの中で直されます。両者を確実に揃え続けられる仕組みは、実のところこれしかありません。
コードレビューで一緒に見る。 ある変更によって文書が間違いになるのなら、それは他の指摘と何ら変わらないレビューコメントです。使える習慣のなかでいちばんてこが効き、しかも費用はかかりません。
試せるものは試す。 パイプラインの中で実際に走るセットアップ手順は、願望であることをやめます。README が三つのコマンドで動くシステムになると主張しているのなら、それを証明するジョブを一つ置いてください。
思いきって消す。 間違った文書は、ない文書より悪いものです。人がそれを信じてしまうからです。何かが古くなり、しかも誰も直さないと分かったら、取り除いたうえで、何が失われたのかだけを書き残してください。
期限のあるものには日付を付ける。 バージョン番号、価格、外部への依存が含まれている記述には日付を添えるべきです。そうすれば読み手は、それをまだ信じてよいのかを自分で判断できます。
これは本当は何のためか
ドキュメントとは、知識が個人に張り付いた状態をやめさせるための仕組みです。得られる利益はそれで全部であり、だからこそ書くべき理由は、美意識の話ではなく事業の話になります。
一人しかデプロイできないシステムは、復旧までの時間がその一人の空き具合と等しくなります。誰も理由を説明できない部品は、作り直されるか、迷信のように温存されるかのどちらかです。どちらも技術デューデリジェンスの指摘事項として出てきますし、どちらも開発者のオンボーディングを長引かせます。二つは服が違うだけの、同じ問題です。
Mecanik はどの案件でも、引き継ぎの一部としてこれらの文書を書きます。ソフトウェア開発の仕事の一部です。そして実際に使われる文書は、ほとんどの場合、依頼された文書よりも短くなります。
よくある質問
技術ドキュメントはなぜ古くなるのですか。 コードから離れた場所にあるため両者を揃えられるかが誰かの記憶頼みになること、意図ではなく実装を書いているためリファクタリングのたびに無効になること、そして持ち主がいないため正確さが特定の誰かの課題になる瞬間が来ないこと、この三つが理由です。リポジトリの中に置き、コードの変更と同じレビューで見直せば、三つとも同時に手当てできます。
ソフトウェアチームはどのドキュメントを保守すべきですか。 四つで価値のほとんどが取れます。システムを動かせるようにする README、形と理由を説明する一ページのアーキテクチャ俯瞰、なぜそう決めたのかを残す追記専用の決定記録、そして実際に起きた障害のためのランブックです。コードがどう動くかの説明は、この一覧には入りません。
決定記録とは何ですか。 ある決定と、検討した代替案と、その選択の理由を書き留めた短いメモです。現在の状態ではなく、ある時点を記録するものなので、あとから更新する必要が生じません。決着した論点を、決着させた制約をもう覚えていない人たちが下手に蒸し返すことも防げます。
技術ドキュメントはどう書けばよいですか。 疲れていて、圧力を受けていて、ただ一つの具体的なことを探している人に向けて書きます。先に答えを書いてあとから説明し、説明ではなく本物のコマンドと本物のパスを載せ、何がうまくいかず、それがどう見えるのかを書き、正しいままでいられる程度に短く保ちます。
古くなったドキュメントは削除すべきですか。 誰も直さないのであれば削除してください。間違った文書は、ない文書より悪いものです。読み手がそれを信じ、そのとおりに動いてしまうからです。削除したうえで何が失われたのかを書き残し、バージョン番号や価格や外部依存を含む記述には日付を添えて、読み手自身が判断できるようにしてください。
コメント