Contents

「死んだ」ドキュメント

開発者たちの働き方には、僕らノンプログラマが見習うべき点が多くあるよ。 中でも、ドキュメントに対する考え方は大切だ──彼らのドキュメントは「生きて」いるんだ。

/images/rusted_wheel.jpg

「生きた」ドキュメントって?

さっそくよくわからない言葉を使っちゃったね。 「生きた」ドキュメントってのは、継続的に更新されるドキュメントのことだよ; 例えばウェブサイトとか、ソフトウェアのマニュアルとかね。 逆に「死んだ」ドキュメントといえば、更新できない形式のドキュメントのことだ。 紙の書籍は、みんな「死んだ」ドキュメントだね。

ぼくがここで言いたいのは、紙の書籍が悪いということではないよ。 むしろ書籍は、「生きた」ドキュメントにする必要はないと思ってる。 だって本の著者の主張や物語の内容って、そんなにコロコロ変わるものではないし、むしろ変わっちゃったら困るよね。 あくまでも適材適所が大事だよ。

それでも僕らノンプログラマは、知的労働には「生きた」ドキュメントが必要なシーンが多いことを、知っておく必要がある。 さっきは、「死んだ」ドキュメント1の例として紙の書籍を挙げてしまったけど、 ドキュメントの「生死」を分けるのは、媒体がデジタルかアナログかの違いではないよ; ペーパーレスに仕事をしていれば OK と言いたいところだけど、話はそう単純じゃないんだ。 たとえ電子ファイルだろうと、情報の流れが淀んでいれば、すぐに「死んで」しまうよ。

「死んだ」ドキュメントとは

もし文書をワープロソフトを開いて「書いて」いるとしたら、「死んだ」ドキュメントを作っている可能性が高い。 僕も経験があるんだけど、よくやってしまうのが報告書の執筆だね。 例えば、表計算ソフトやプログラムでなにか計算をして、その結果をワープロソフトに貼るとき。 どこにも紙は登場していないけど、こうやって作られるドキュメントは紛れもなく「死んで」いるんだ2

知的労働に「生きた」ドキュメントが必要であることを腹落ちするためには、「死んだ」ドキュメントの弊害を理解するのが近道だと思うな。 見ていこう。

「死んで」いると、なぜ悪い?

「死んだ」ドキュメントの問題を上げればキリがないのだけど、とくに重要なのは三つだよ:

  • 品質を積み上げられない
  • 変化に対応できない
  • what に着目できない

品質を積み上げられない

品質って、大事だよね。 品質にはいくつかの段階があって、「当り前品質」と「魅力品質」[@kano1984-attrac-qualit-jp] に分けて整理すると考えやすいよ。

どんな品質項目がどちらのカテゴリに分類されるかは、その製品のミッションによって変わってくる。 話をすすめる前に、まず具体的な製品を思い浮かべようか──よし、報告書にしよう3

報告書のミッションはもちろん、仕事の結果を報告することだよね。 だいたい図表が入っていることが多くて、文中にも、数字について言及があるかもしれない。 報告書の当たり前品質はもちろん、データに間違いがないことだけど、 実はこの「間違い」というやつも、なかなか厄介なんだ; 昔は正しかった値も、元データが更新されてしまえば、とたんに「間違った」値になってしまうからね。 とにかく、プロジェクトの実態と異なるデータが載っている報告書は、当り前品質を満たしていないことになる。 成果物として失格だ。

魅力的品質はどうかな。 当たり前品質との線引きが難しいこともあるけれど、 「文が読みやすい」 「図表が理解しやすい」 あとは「プロジェクトの全体像がすぐに分かるし、必要であれば詳細も調べることができる」とか、そんなところだろう。 じゃ、「全体の美観が整っている」というポイントはどうだろう? なんだかフワッとした言い方だけど、けっこう大事かもしれないよ。 たとえ数値が正しくても、図表の配置がめちゃくちゃだったら、 読み手はデータの正確性を疑ってしまうかもしれないからね。

報告書に限った話ではないけれど、よい仕事をするには、当たり前品質を死守しつつ、魅力品質を高めていく必要がある。

変化に対応できない

仕事をとりまく状況は、刻々と変化する。 「変化こそ不変の真理である」というやつだね4

「死んだ」ドキュメントは、変化への対応が苦手だ。 対応の遅れをカバーするために、余計なコストがかかることも多いよ。 ちょうど、書籍の誤りが発覚した時に、出版社が正誤表を差し込まないといけなくなるのと同じだ。

ここでも、媒体が紙であること自体が悪いわけではないよ。 対応の遅れが生じる原因は、成果物が情報源から切り離されていることだ5。 紙の書籍は、印刷によって、原稿という情報源から切り離されるよね。 web サイトは紙よりは修正しやすいけれど、情報源と切り離されてしまったら、同じことが起こるよ; 地図サービスに表示されている「営業中」を信じてお店に行ってみたら臨時休業だったってこと、ないかな? これも、現在の状況という情報源から、web サイトが切り離されているために起きている6。 書籍の例と、本質的には同じだ。

訪ねた店が休みだったら、諦めてほかの店に行けばいい。 だけど仕事においては、変化に対する対応の遅れは重大な問題を引き起こすよ──混乱を招き、生産性を低下させるんだ。 変化に対応できない働き方をしていると、負のスパイラルから抜け出せなくなる。 ワークフローの改善自体も変化を伴うからね。 変化に対応できる仕組みが、仕事で使うドキュメントには不可欠だよ。

「what」に着目できない

ドキュメントには、コミュニケーションとしての側面もあるよね。 報告書だと説明しにくいから、ここでは具体例を「手順書」にしようかな。

手順書のおかげで、後任の人に指示を出すことができる。 でもみんな、手順書の致命的な欠点には気づいているかな?──あれこれ指示を出すくせに、それ自体は仕事をしてくれないことだよ。 手順書を見ながら、あくまでも作業者が手を動かす必要がある。 厳しいことを言えば、「手順書を読む」という、新しい仕事を増やしているとも言えるね。

ちょっと突拍子もない問いをするけど、手順書を執筆した前任者のほんとうの望みって、なんだろう? これは仕事において大切な、「what」についての問いだよ。 もちろん手順書は、後任に確実に仕事を引き継いでもらうために書くのだけれど、それは「what」の答えじゃない。 執筆者がほんとうに望んでいるのは「プロジェクトが期待する状態になっていること」だ。 もしそれができるなら、手順書なんてそもそも必要ないんだよね。 またの機会に紹介するけど、開発者たちは動く手順書: プログラムを使って、プロジェクトを期待する状態に維持するよ。

「死んだ」ドキュメントを使っている限り、僕らは「ドキュメントが仕事をしてくれる」という概念に近づくことができない。 つい、仕事の「what」を忘れがちになってしまうんだよね。 その仕事は本当に必要か、自分は顧客に何を提供しようとしているのかを、常に見つめ直すことが必要だよ。

まとめ

少し長くなってしまったけど、「死んだ」ドキュメントの弊害をみてきたね。 このドキュメントは、品質がいつまでたっても安定しない困りものだ。 また、変化にすぐ対応できないせいで、さらなる問題を引き起こしてしまう。 なにより、「ほんとうはどうなっていたいのか」に着目した働き方から、我々を遠ざけてしまうんだったね。

これらの悲劇を、開発者たちがどうやって回避しているのか、気になってきたんじゃないかな。 彼らの「生きたドキュメント」の紹介、楽しみにしててね🕺


  1. いち愛好家としては、書籍のことを「死んだ」ドキュメントと表現したくないな。「静的ドキュメント」の方がいいかもね。 ↩︎

  2. どうしてもワープロソフトで報告書を書きたいなら、表計算ソフトのデータは少なくともリンクとして貼り付けよう。報告書がデータの更新に追従するようになるよ。 ↩︎

  3. 我ながら、つくづく報告書が好きだなぁと思うよ。いろんな点から、例としてとっても便利なんだよね。 ↩︎

  4. 宇宙の真理に反するファイル名「最終版」は、もはや OS レベルで警告を出してはどうだろう?拡張子を変えようとしたときみたいに。 ↩︎

  5. というか、これが「『死んだ』ドキュメント」の定義かもね。 ↩︎

  6. シャッターを開閉するときに web に情報が送信されるようにすれば、解決するかな。 ↩︎