リーダブルドキュメント / The art of readable document
この記事は チームスピリット Advent Calendar 2019 の4日目の記事です。
読みやすく、理解しやすいドキュメントを書いていますか？
ソフトウェアエンジニアの中にはソースコードの書き方については自信があってもドキュメントの書き方には自信がない方もいるのではないでしょうか？
プログラミングを生業にしている人の中には「リーダブルコード」を読んだことがある人も多いでしょう。実は、ソースコードもドキュメントも読みやすく、理解しやすく書くことが優れたコードであり、ドキュメントであると言えます。
ここでは、馴染み深い「リーダブルコード」を題材に、読みやすく、理解しやすいドキュメントについて考えてみたいと思います。そのため、ここで記載した内容には書籍「リーダブルコード」に書かれている内容を多く引用しています。
理解しやすいドキュメント
「ドキュメントは理解しやすくなければいけない」
コード以上にドキュメントは理解しやすくなければいけません。これは何かを書く上での一番大切な原則です。
読みやすさの基本定理
「ドキュメントは他の人が最短時間で理解できるように書かなければいけない」
自分だけのメモは自分さえ理解できれば問題ない、と書き散らかしていたりしませんか？
将来の自分も実のところ他人です。そう、過去の自分が書いたドキュメントを見て理解できず絶望するのです。
最小限にまとめられたドキュメントは短いかもしれませんが、理解するために時間を要するようでは読みやすいドキュメントとは言えません。
説明や具体例が詳しく書かれており省略して簡潔にしたくなったとしても、常に一歩下がって「このドキュメントは理解しやすいだろうか？」自問自答してみることが大切です。
他の人が自分のドキュメントを理解しやすいか考えることは大変なことです。しかし、他の人が最短時間で理解できるように書くようにすることを受け入れれば、あなたはきっと優秀なドキュメントライターになれるはずです。
名前に情報を埋め込む明確な文章を書く
明確な文章を書く
プログラミングであれば、クラス名、メソッド名、変数名などに如何に情報を埋め込むか、によってソースコードの読みやすさ、理解しやすさが大きく変わります。
これはドキュメントでも同様です。文章が簡潔かつ明確に表現されていないと理解しにくいドキュメントとなってしまいます。
例えば、「〜することができる」は「〜できる」で表現できることが多く、文章は短いほうが理解しやすいため、できるだけ後者で記載したほうがよいでしょう。
また、文は受動態ではなく能動態で書く、「〜こと」「〜という」はなるべく使わない、などを気をつけると読みやすいドキュメントとなります。
誤解されない文章
文章が「他の意味と間違えられることはないだろうか？」と何度も自問自答する
文章を曖昧に書いてしまうと、他の意味と間違えられることがあります。例えば、仕様書で条件について記載していると書いてしまうのが「二重否定」です。
二重否定とは「〜ではない場合は〜しない」のような表現のことです。二重否定で条件を記載してしまうと結局どういう条件なのかすぐには理解できなくなってしまいますので、避けるべき書き方です。
美しさ
美しいソースコードは「目に優しい」ものでなければいけません。
美しいドキュメントも同様に「目に優しい」ものになります。
文章ではソースコードと同様にレイアウトされます。適切にインデントされる、関連するものをまとめてブロックにする、といったレイアウト上の工夫はソースコードであってもドキュメントであっても同様に美しさを保つために重要です。
制御フローを読みやすくする
条件やループなどの制御フローはできるだけ「自然」にする。コードの読み手が立ち止まったり読み返したりしないように書く。
ソースコードでは制御フローを並べて記述し、一連の処理を組み立てます。ドキュメントでは制御フローは基本的にはありませんが、文章を順番に並べて一連の意味ある文章を組み立てます。
最終的にはAはBである、と説明したいとき、AやBが自明ではない場合はまずはAやBの説明する、そしてAはBであることを説明する、というように順番に説明します。これがドキュメントにおける制御フローになります。
ドキュメントの制御フローとしては、序論・本論・結論、起承転結などがあります。特に、結論を最初に記載しその裏付けを後述する構成はビジネスや論文などではよく用いられます。
このようにドキュメントもどういった順番で説明していくか、そのための構成をどう組み立てるかを考えることで、読みやすく理解しやすいドキュメントを書くことができるようになります。
巨大な説明を分割する
プログラムでは巨大な式は理解できないため、関数にまとめるなど理解可能な単位に分けていきます。
ドキュメントでも詳細が長くなってしまう場合は、一旦説明した内容を表す用語を定義したり、別章に詳細な説明を記載したりします。
巨大な説明を一つの文章で理解しようとすると難しい。そこで、巨大な説明を分割して、読み手が一つずつ飲み込めるようにします。
ドキュメントの再構成
コードを読みやすくするために、プログラムを再構成する。
ドキュメントでも同様に再構成（推敲）することでドキュメントを読みやすくできます。こうすることで、読み手としても一つの目標に向かう説明をまとめて読むことができるので、最短時間で理解できるようになります。
無関係の下位問題を積極的に見つけて抽出する
ドキュメントでも詳細化していく中で無関係な文章が混じってしまう場合があります。この文章は本来説明したいことを邪魔して読みにくくしてしまうので、別の場所に移して記述することが望ましいです。
こうすることで、読み手としても一つの目標に向かう説明をまとめて読むことができるので、最短時間で理解できるようになります。
一度に一つのことを
コードは1つずつタスクを行うようにしなければなりません。一度に複数のことをやると理解が難しくなってきます。
これはドキュメントでも同様です。一つの文章には一つのことを、一つの段落には一つのことを、一つの章には一つのことを。このように分けて書くことで目次を見たり、ザッピングしたりしたときに目的のドキュメントを見つけやすくできます。
ドキュメントに思いを込める
おばあちゃんがわかるように説明できなければ、本当に理解したとは言えない ーアルバート・アインシュタイン
誰に何を伝えたいかによって、何を書くべきか、どこまで書くべきかは変化してきます。複雑な考え方を伝えようとするときに、細かなことまで話し過ぎてしまうと相手を混乱せてしまうことがあります。
自分よりも知識が少ない相手に理解してもらえるように相手に伝わるような「簡単な言葉」で説明することが大切です。自分の考えを整理しエッセンスを伝えたり、相手が理解しやすい具体的な例題を用いて説明したり。
まとめ
いかがでしたでしょうか？
ソースコードを読みやすく、理解しやすいものにしていく原則やルールをベースにドキュメントを読みやすく、理解しやすくする方法をまとめてみました。
ソースコードも文章も同様に言語で他の人に伝えるものだと考えれば、自ずとどのように考えて書けばよいか分かってきます。読みやすく、理解しやすい美しいソースコードを書けている方はきっと美しい文章も書けるはずです。
読みやすい、理解しやすい文章を書くことに興味が湧いてきた方は何かしら文章術に関する書籍を1冊読んでみましょう。どのようにして冗長な表現を削り、必要なことを漏らさず記載していくかサポートしてくれます。
文章術に関連する書籍も多いので、私のオススメを1冊紹介しておきます。ご参考まで。
Enjoy Advent Calendar!
この記事が気に入ったらサポートをしてみませんか？