はじめに
こんにちは。カナリーソフトウェアエンジニアの村山です。4月にカナリーへ入社してから、もう2ヶ月以上が経過しており、時の流れの速さを感じています。
ところで、私は人から「ドキュメントがわかりやすいですね」とお褒めの言葉をいただくことがあります。大変嬉しいお言葉をいただき、あらためて「ドキュメント作りで普段自分が意識していることってなんだろう？」と考えてみることにしました。
この記事では、わかりやすいドキュメントを書くうえで、私が工夫していることを紹介します。日常的に技術ドキュメントを作成するエンジニアを主な読者として想定しています。
「わかりやすいドキュメント」とは何か
本題へ入る前に、「わかりやすいドキュメント」の定義を考えたいと思います。私にとってわかりやすいとは、「読み手を置いてけぼりにしない」ことです。読み手が「あれ、これってどういうことなんだろう？」とか「うーん、よくわからないなぁ」ともやもやすると、しだいにドキュメントから取り残されてしまいます。結果的に伝えたかったことが伝わらないままになります。つまり、「わかりやすいドキュメント」とは「読み手を置いてけぼりにしないドキュメント」を指します。
ところで、ドキュメントには「網羅性」「正確性」「わかりやすさ」といった観点があります。
どれも重要な要素ですが、すべてを同時に達成するのは困難です。そのため、ドキュメントのテーマによっては、網羅性は犠牲になる代わりに正確性が優先されたり、あるいは正確性は犠牲になるけれどもわかりやすさが重視されたりするわけです。
私の書くドキュメントはどちらかというと、読み手にとってわかりやすいものであるようです。では、なぜわかりやすいことが大切なのでしょうか。次はその理由について私の考えをご紹介します。
なぜ「わかりやすいドキュメント」を書く必要があるのか
私が「わかりやすいドキュメント作り」を心がけてきたのは、そのドキュメントをなるべくたくさんの人に読んでもらいたいからです。
私は社内向けのドキュメントしか執筆したことがありません。つまりOSSや技術記事といった分野ではドキュメントを残した経験があまりありません。その狭い経験において痛感したことは、「ドキュメントを一生懸命作っても、あまり読まれない」という事実です。手塩にかけて大切に育んだとしても、その存在自体が人々の記憶から消え失せ、埃を被ることがあります。
ドキュメントは人に読まれ、理解してもらうことでようやく価値を発揮します。では、読まれて理解してもらうには何が大事なのかと言うと、読み手を置いてけぼりにしないことです。私はこれまで、読者を置き去りにしないように気をつけて文章を書いてきた節があります。そうすることで、多少なりとも「読まれる」確率を上げてきました。
読者のみなさんの中には、普段ドキュメント作りを頑張っているが、あまり読んでもらえないとか、読んではもらえるけど評判が悪い、といった悩みを抱えている方がいらっしゃるかもしれません。本記事がそんな方の助けになれば幸いです。
わかりやすいドキュメントを書くために工夫していること
基本編
基本編では、わかりやすいドキュメント作りのための基本的な手法を紹介します。ドキュメント作りにお悩みの方は、この基本事項を守るだけでも一定の効果が見込めるのではないでしょうか。
正しい日本語を使う
これは基本中の基本で、「そんなの当たり前でしょ！」と思われるかもしれませんが、日本語として間違っていないかどうかが、文章のわかりやすさに大きく影響してきます。別に小説家のような美しい文章を書かなくてはいけないというわけではありません。「てにをは」の誤りや誤字脱字がないか、主語がねじれていないかなど、日本語における基本部分を気をつけるだけで問題ありません。
しかしながら、往々にして私たちは誤った日本語を文章に書き起こしてしまいます。それは私も例外ではありません。その理由の1つに、普段口頭でやりとりするときや、チャットのメッセージで意思疎通を図るときは、正しい日本語でなくとも十分コミュニケーションを取れることがあります。多少砕けた言葉でも、相手にきちんと伝われば問題ないからですね。
一方で、ドキュメントに不正確な日本語を使ってしまうと、読み手はその部分にいちいち引っかかったり、意味が理解できずに置いてけぼりにされたりすることがあります。そのためなるべく正しい日本語で文章を書く必要があります。
たとえば、Google社が提供しているテクニカルライティングの講座では、最初に英文法の基本を紹介しています。これを一番に紹介しているのは、ひとえに正しい文法を使うことの重要性を説いているからでしょう。
「そもそも正しい日本語とは何で、どうやって書けばいいか分からない」ということであれば、下記のように、テクニカルライティングに限定しない、一般的な文章指南の書籍を読むことをおすすめします。いずれも読みやすく、専門的な知識を必要としないので気軽に手に取ることができます。
易しくシンプルな日本語を使う
正しい日本語を使うことと同じくらい重要なことは、できる限り簡単で無駄のない言葉を使うことです。これはなにも技術用語や専門用語を用いない、ということではありません。技術者がドキュメントを残す以上、それら専門的な用語を避けて通ることはできません。ここではあくまで、基本的な言い回しや伝え方において、易しくシンプルな日本語を使おう、ということです。
下記はAIに考えてもらった、難しく複雑な文です。
当該機能における挙動の確認作業を実施する際には、事前に関連ドキュメントに目を通したうえで、必要に応じて適宜担当部署への照会を行うことが望ましいと考えられます。
これを易しくシンプルな日本語で言い換えると、下記のようになります。
機能を確認する前に、関連するドキュメントを読みましょう。必要があれば、担当者に確認してください。
もちろん、公的文書を作るうえでは1つ目のような文がふさわしいかもしれませんが、わかりやすいドキュメント作りという意味では2つ目が好まれるでしょう。
ただ、難解で回りくどい文章は、書き手本人でも気付かないうちに自然と生み出されることが多いです。私もついついそういった文を書いてしまいがちです。では、そういった文に自分で気づくためにはどうすればいいでしょうか。下記では私が文章を見直す際の観点をまとめているので、参考になれば幸いです。
- 一文が長くなっていないか
- 漢字がやたら多く使われていないか
- 読点（
,）がしつこく登場していないか - 頻繁に体言止めを用いていないか
- 不必要に受動態を利用していないか
書いた後に「声に出して」読む
なんだか国語の授業のように思われるかもしれませんが、実際に音読してみることが効果的です。前述の「正しい日本語を使う」でも言及しましたが、ドキュメント作りでは正確な言葉や文法を使うことが大切です。では、間違った言葉や文法を見つけるためにはどうすれば良いのかというと、手っ取り早い方法が声に出して読み上げることです。何も大声で部屋中に響き渡るように音読する必要はありません。小さな声でボソボソと素早く読み上げるだけで十分です。すると案外、誤字脱字や誤った文法の使用、長すぎる一文に気がつくことがあります。
ドキュメントを作った後は推敲（すいこう）することが大切です。推敲とは、文章をより良くするためにあれこれやってみることです。別の語彙を採用したり、不要な部分を消したり、あるいは付け加えたりします。推敲の手段はなんでもかまいません。同僚にレビューをお願いして指摘してもらうのもいいですし、AIに添削させるのもいいでしょう。書き終えた後に休憩を挟み、リフレッシュした頭で最初から読み返すことも重要です。とにかくやり方はなんでもいいので、作り上げたドキュメントをいきなり完成とするのではなく、もう一度練り直してみようということです。声に出して読むのは、手っ取り早く推敲できる手段なので今回紹介しました。
推敲するうえで、具体的にどんな観点でチェックすればいいかについては、下記の記事をご確認ください。
整理をしてからドキュメントを書く
ドキュメント作りにおいてありがちなのが、いざ完成したものを読んでみると、内容に一貫性がなかったり、結論が不明確だったり、根拠が不十分だったりするなど、完成度が予想よりも低いことです。
自分自身でも結論やテーマが不明確なまま、勢いよく書き始めてしまうと、結果的にとりとめもない文章ができ上がってしまいます。これを避けるためには、執筆を始める前に伝えたいことや結論、根拠となる事実をあらかじめ整理しておきます。ノートやメモアプリでもなんでもいいので、そこに手持ちの情報や考えを記載します。
さらに効果的なのが、あらかじめ定められたフォーマットを利用して整理することです。フォーマットに従うことで、効率的に知識や情報をまとめることができますし、あとでその内容を直接ドキュメントに落とし込むことが可能です。たとえば、下記は弊社で運用しているADRの記載項目です。シンプルながらも効果的な項目で、エンジニアはこれらを埋めることでADRを作成します。
背景
決定内容
決定理由と他の選択肢との比較
影響範囲
このように形式化することで、書き手ごとに記載方法が異なる事態を避けられます。そして何より、エンジニアはADRの下書きを書く段階で、情報を整理しつつドキュメントを作成できます。ドキュメントのフォーマットが定められていると、効率的に執筆を進められます。
弊社ADRの具体的な運用方法については、下記テックブログをご参照ください。
発展編
発展編では、ドキュメントをさらにわかりやすくするための工夫についてまとめています。基本編のポイントを実践したうえで、これらを意識するのが良いでしょう。
テーマをきちんと練る
ドキュメントを書くうえで大切なことは、「このドキュメントでは何を伝えたいか」を明確にしたうえで執筆することです。それがふわっとしたまま書き始めてしまうと、全体がとりとめもないものになってしまいます。また、「あれもこれも伝えたい！」とテーマを盛りだくさんにすると、ドキュメント全体が膨れ上がり、結局伝えたいことが伝わりにくくなります。
つまり、テーマを明確に定めることで過不足のないドキュメントを作ることができます。テーマとは主題のことであり、そのドキュメントで伝えたい主な内容のことです。
以下は、私がドキュメント作成をする際に守っている順序です。
- そのドキュメントで伝えたいこと、つまりテーマを明らかにする
- 1で言語化したテーマをブラッシュアップする
- そのテーマに沿ってドキュメントを執筆する
たとえば、社内エンジニア向けに、とある運用作業の手順書を作るとします。私は請求業務自動化SaaSを扱う会社のエンジニアです。ユーザーは弊社サービスを通じて、諸々の請求業務を手間なく進めることができます。今回作る手順書は多くのエンジニアが目にし、それに沿って作業するため、誤りがないのは当然のこと、誤解を生まないドキュメントにする必要があります。では、実際に書く前に手順書のテーマを決めましょう。これが前述の1の部分です。
明細書・請求書の手動発行対応について説明する
まずは上記のテーマを定めたとします。しかしこの内容では、以下のことがわかりません。
- 具体的に何の明細書・請求書なのか。ユーザーが弊社提供のサービスを通じて発行するものか、あるいは社内で作成して取引先に提出する内部的なものか、分からない。
- どんなときに手動発行するのか。何かイレギュラーな事態が発生したときなのか、それとも定常的に発生するのか。
- 明細書と請求書の発行対応は、同時に行うものなのか。それとも依頼の粒度によってまちまちなのか。
テーマ自体にまだまだブラッシュアップが必要なようです。2の作業として、上記の問いに答えるため、あらためて情報を整理してみます。既知の情報を並べたり、不明点があれば関係者に質問して疑問を解消します。すると下記のようになりました。
- 明細書および請求書は、ユーザーが弊社サービスを通じて発行する書類である。書類はPDF形式で発行される。
- 本来は弊社サービスを利用すれば問題なく発行できるが、稀にユーザー起因で発行できない場合がある。その理由はさまざまであり、基本的には先方で原因の特定および解消をお願いしている。しかし、緊急性が高い場合は、顧客との関係性を維持したい背景もあり、弊社カスタマーサポートを通じてエンジニアに手動発行の依頼が来る。また、依頼によっては2つを同時に発行するケースや、片方のみを発行するケースがある。
- 明細書と請求書を手動発行する場合、専用のスクリプトを実行する。スクリプトはそれぞれ別々に用意されており、どちらも処理内容が異なるため、スクリプトを統合できない。
- 発行作業が完了したら、カスタマーサポートチームに共有する。
このように整理できました。
スクリプトは別々に用意されており、それらを1つのスクリプトにまとめることは不可能そうです。また、明細書と請求書の発行依頼は、2つ同時に来ることもあれば、1つだけという場合もあるようです。これらのことから、両者の発行方法は別々の手順書にまとめたほうが良さそうです。
そこで、テーマを小分けにし、それぞれで手順書を作ることにしました。後はこのテーマに沿って2つの手順書を作るだけです。
ユーザー起因で発行できない明細書を、エンジニアがスクリプトを用いて発行し、カスタマーサポートチームに共有するまでの手順を説明する
ユーザー起因で発行できない請求書を、エンジニアがスクリプトを用いて発行し、カスタマーサポートチームに共有するまでの手順を説明する
これらの過程を踏まえることで、テーマを詳細化し、適切に分解できました。後は3番の作業として実際に執筆を進めていきます。少なくともテーマから逸脱しないよう気をつけていれば、内容が不必要に発散することはありません。説明したいことがいつもぐちゃぐちゃになってしまう、とお悩みの方は、まずはテーマをしっかりと練ることから始めると良いかもしれません。
論理的であることを意識する
ドキュメントは論理的である必要があります。しかし、そもそも論理的ってどういうことでしょうか？ 論理的じゃないドキュメントはどうしてダメなんでしょうか？
『エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック』という書籍では、「4-1 そもそもロジカルシンキングとは？」の章で下記のように説明しています。
物事を体系的に整理し、矛盾や飛躍のない筋道を立てることができれば論理的と言えます
なるほど、確かに情報が体系化されておらず、漏れとか重複があるようなドキュメントは、読み手に誤読され、伝えたいことが不明瞭になる可能性があります。また、書いていることがちぐはぐだったり、十分な理由が示されていないまま結論が導きだされていたりしてもいけません。
とくに、わかりやすいという意味では後半の「矛盾や飛躍のない」部分が重要になってきます。ドキュメントを体系的にすることも大切ですが、本記事では割愛します。
具体例として、矛盾や飛躍を含んだ文章を紹介します。これもAIに考えてもらいました。
矛盾した文章
弊社の新機能は、すべてのユーザーが無料で利用できます。ただし、プレミアムユーザーのみが利用可能です。
「いや無料で利用できるんじゃないんかい！」と突っ込みたくなるような文章ですね。これはあくまでわかりやすい例で、こういった誤りをする人はさすが少ないと思います。ですが、ドキュメント自体が長大で複雑になると、気が付かないうちに矛盾が生じてしまいます。
結論が飛躍した文章
弊社のサービスは月間アクティブユーザーが10万人を突破しました。そのため、来月から料金を2倍に値上げします。
「なんでやねん！」という声が飛んできそうですね。どうして10万人を突破したら料金が値上げされるのか、まったくわかりません。書き手は納得していても、いざ文章にして他人に読んでもらうと、たちまち論理の飛躍が見つかることが多々あります。
では、こういった矛盾や飛躍を見つけるためにはどうすればいいでしょうか？ 私がやってみたように、自分の文章にひたすらツッコミすることも効果的でしょう。「なんで？」とか「どうやって？」と自分で投げかけ、それに答えていくことで、思いがけない論理の誤りを見つけることができます。
また、「結論を導くための理由に不足や誤りはないか」を考えることも大切です。
今朝、APIが稼働しているコンテナが一時的に停止した。同時間帯では期間限定キャンペーンが実施されており、リクエスト数が普段より増大していた。きっとこのキャンペーンがコンテナ停止の原因に違いない
上記の説明だと、コンテナが停止した原因は期間限定キャンペーンによるスパイクとしています。しかし本当にそうでしょうか？ 確かにコンテナの停止とキャンペーンの時刻は一致していますが、たまたまタイミングが合っただけかもしれません。要因は別にあるかもしれず、まずはコンテナが停止したときのログや、関連するメトリクスを調べてみることが先決でしょう。
理由や原因を探るときは、幅広く、取りこぼしがないように調べる必要があります。つまり、漏れなくダブりなくを意識します。この「漏れなくダブりなく」といった考え方をMECE(Mutually Exclusive and Collectively Exhaustive)と言います。MECEについては下記の記事をご確認ください。
とはいえ、無鉄砲に漏れなくダブりなく考えようとしても大変なので、適宜フレームワークを用いて整理することが大切です。前述の『エンジニアが知っておきたい思考の整理術 複雑な情報を【理解する】【伝える】テクニック』では、ロジックツリーを用いたロジカルシンキングを推奨しています。ロジックツリーの手法についてはネット上にも多くの記事があるため、気になる方はぜひ調べてみてください。
背景を丁寧に記述する
ドキュメントでは背景を説明することが大事です。なぜなら、背景が丁寧に書かれていれば、読み手が出だしから置いてけぼりにされることはないからです。
背景の説明が不十分だと、前提となる知識や認識が不揃いのまま読み進めることになってしまいます。結果的に、肝心の結論部分をうまく理解できない、あるいは誤解したまま読み終えてしまうといった事態が発生します。
背景を書く前に大切なことは、対象となる読者を想定した上で情報を整理することです。すべての読者にとってわかりやすいドキュメントを書くことは困難なので、情報を取捨選択するためにこの作業が必要となります。読者がエンジニアなのか、それとも非エンジニアなのか、もしエンジニアだとしても、フロントエンドエンジニアなのか、あるいはバックエンドエンジニアなのか。対象によってドキュメントの内容を調整する必要があります。
読者の想定と情報整理については、Googleのテクニカルライティングの講座「Audience」でも説明されています。こちらの講座が素晴らしいため、ここでの説明は割愛します。
読者をきちんと想定できたら、その読者がスムーズにドキュメントに入っていけるよう、背景を書いていきます。背景は以下の順番で記述します。
- 前提となる事情を整理する
- このドキュメントを書くに至った出来事や状況を説明することで、読者の立ち位置を揃える。
- 読者が当然知っているであろう情報は細かく説明しない。
- 読者にとって未知の情報が登場する場合、適度に説明し、必要であれば注釈や参考サイトのURLを添付する。ただし、注釈や参考サイトがなければまったく理解できない、という事態は避けるようにする。
- 発生している課題を明らかにする
- 何が問題になっていて、なぜ対処しなくてはならないかを説明する。
- 問題と、それを対処すべき理由との間に、矛盾や飛躍がないよう注意する。
- ドキュメントの目的を述べる
- 何を明らかにし、何を成し遂げたいのかを明記する。
- また、このドキュメントでは「何に言及しないか」を明示することも重要である。最初に断っておくことで、読者が余計な考えを抱かず、ドキュメントに集中できる。
背景が丁寧に記述されていれば、読者はその後の文章を円滑に読み進めることができます。ひいては、ドキュメントが最後まで読まれる確率が上がります。せっかくドキュメントを書いたのに読者が途中で脱落してしまう、という場合は、背景部分を見直してみると良いでしょう。
おわりに
以上、わかりやすいドキュメントを書くために私が工夫していることを紹介しました。長々と説明しましたが、私自身、より良いドキュメント作りをするために日々学んでいるところです。もっと良い手法や観点をご存知の方がいらっしゃいましたら、教えていただけると幸いです。
最後に、弊社ではADRやRunbookをはじめとしたドキュメント文化があり、日々多くのドキュメントが作られ、同時にレビューされています。
もし弊社のドキュメント文化に興味をお持ちいただけた方は、ぜひカジュアル面談にお越しください！
最後までお読みいただき、ありがとうございました！
Discussion