分かりやすいドキュメントとは
エンジニアの仕事の大半は、実はドキュメント作成だったりする。
コードを書くだけでエンジニアの仕事は終わりと思われるかもしれないが、コードを書く前には詳細設計書やら基本設計書を書く必要があるし、書き上げたコードに対するテストの設計書もある。作成したシステムのメンテナンスや運用もドキュメント化して管理する。そもそも作るシステムの要件/要求もドキュメント化して整理されている。
エンジニアが最も使えないといけない言語は、JavaやPythonといったプログラミング言語よりも日本語……という話があるが、これはとても正しいと思う。
ドキュメント化する際には、ドキュメントの目的や意図に沿って、過不足ないように情報を整理し、誰にでも誤解なく伝わるように言語化する力が求められる。これぞ正しく「日本語を使える」ということなのだろう。しかし残念なことに、日本語の読み書きができることと、「日本語を使える」ということは同じではないのだ。
日本語で書いてあるはずなのに内容が頭に入ってこない資料を、皆さんは読んだことがあるはずだ。知らない単語やフレーズばかりの英語長文を読んでいるのと同じ感覚を、日本語の文章で感じたことがあるはずだ。
例えば。
エンジニアがシステムを作る上で何度も見ることとなる「設計書」は、非エンジニアが読んだところで全く意味が分からないだろう。逆に経理部が作る（とブログ主は思ってる）「帳簿」は、エンジニアが見たところで意味が分からない。
これらは例えとしては極端だと思われるかもしれない。しかし、こういった前提知識が共有されていない資料は読んでも理解できないというのは当たり前なのだ。知らない英単語ばかり使われている英語長文が読むのが大変なように、読み手の技量を要求するドキュメントはストレスになる。
分かりやすいドキュメントとは、そういった読み手の技量を可能な限り要求しないように、ストレスを減らす工夫が徹底された優しさに満ちた親切なドキュメントではないだろうか。
親切なドキュメント
開発現場におけるドキュメントにはフォーマットが用意されている。そのフォーマットに沿って記載を進めれば、基本的に読み手に親切なドキュメントとなるのは大前提である。
ドキュメントを読む上での順番や粒度がルールとして決まっていれば、ドキュメントのどこに欲しい情報があるのかを探す手間が省ける。作成する側としても、全体の構成を考える必要がなくなるのだ。
となると作成者が読み手に対してできる優しさはフォーマットを崩さない範囲に限られてくる。フォーマットにもよるだろうが、パッと思いつく優しさとして、自分が実践しているものは下記の3つになる。
- 読み手で前提知識が共有されていないフレーズは補足する
- 表記揺れを徹底的に排除する
- 上から下（左から右）へと順番通りに見れば内容が分かる
「読み手で前提知識が共有されていないフレーズは補足する」としては、システムや設計書内でしか使われないフレーズについては、その意味や引用元などを明確化するようにしている。後から見た時に、意味を忘れていたとしても調べることができるように、追跡ができるような補足をするようにしている。
「表記揺れを徹底的に排除する」というのは、同じ意味を持つ違うフレーズが入り乱れる文章は、単純にストレスになるからだ。名前が違えば意味や使い道が違うということを明確にしている。
「上から下（左から右）へと順番通りに見れば内容が分かる」というのは、資料を読み進めた後、また元のページに戻るような作りにはしないようにしている。考え方としては、口頭でドキュメントの説明をする際にページを読み進めるだけで、滞りなく説明できるようなドキュメント作成に努めている。
他にもできるだけ表や図は用いるようにしたり、大事なところは太字にしたり色を変えたり（とはいえ使いすぎないようにしたり）という工夫は欠かさない。それらは全て手間ではあるが、その後、多くの人が見ることになるドキュメントの手を抜くことは、その後ドキュメントを作ったことも忘れたくらいの頃まで引き摺ることになる爆弾となりかねない。
ほんの少しでもドキュメントを見る人への優しさを抱いてドキュメントを作ってみては如何だろうか。
ドキュメントレビューでの指摘
そんな優しいドキュメント作成を心がけているブログ主は、後輩のドキュメントのレビューをすることが増えてきた。
その際にはドキュメントの見やすさの指摘もするようにしている。ドキュメント作成の目的として、皆等しく「思考を整理すること」が暗黙的に含まれていると考えているからだ。
そんなドキュメントのレビューの目的の一つとして、「思考が整理できていること」を客観的に追求することが含まれていると思う。ドキュメントの流れが飛び飛びになっていたら、かなりの確率でその部分に課題を抱えている。そういったことを指摘するだけでも、意識していなかった思考の抜けを再考する機会を与えられる。
分かりやすいドキュメントであれば、設計の不備なども外から指摘しやすくなる。レビューにおける議論がスムーズに進む。ドキュメント化を蔑ろにしているならば、その案件はバグをレビューで発見できる可能性を低くしてしまっているように思う。
設計開発の現場において、バグがゼロはほとんどあり得ない。規模が大きければ大きいほど、その傾向は強い。そんな現場でできる品質向上の大前提は、バグや設計漏れを見つけられるチャンスを増やすしかない。
本当に分かりやすく素晴らしいドキュメントとは、品質を上げられるドキュメントなのではないだろうか。
