読み手ファーストな技術文書の書き方 ─ 社内SEのための情報共有術
はじめに
本記事では、社内外における情報共有の重要性と、その内容について取り上げます。せっかくドキュメント化したのに読まれず、結局問い合わせを受けることが多い、という課題はないでしょうか。社内のメンバーをサポートすることの多い社内SEにとって、問い合わせを減らせれば業務が効率化されるだけでなく、自身の評価も上がることでしょう。
そこで、考えたいのが「読み手ファースト」な技術文書の書き方です。読み手ファーストとは、読者の立場に立って情報を提供することを意味します。読者が求める情報を的確に提供し、情報共有の効果を高めるのが目的です。
読み手ファーストな技術文書の基本原則
読み手ファーストということは「自分たちが何を伝えるのか」ではなく、「相手が何を知りたがっているのか」という考え方になります。そのため、以下のポイントを意識して技術文書を書くことが重要です。
- 誰が読むのか？
ターゲットを明確にする - 文章の目的を最初に示す
WHY, WHAT, HOW の順で書く - 情報を簡潔に整理する
KISS（Keep It Simple and Stupid）の原則
誰が読むのか？
対象者をあらかじめ定義します。対象者の持っている知識、業務内容、関心事を考慮して設定します。例えば、以下のような対象者を想定してみましょう。
- 発注担当者
- 入社歴1年未満
- 業務システムの理解度が低い
- プログラミング経験がない
こういった方を対象にドキュメントを書く場合、当然社内用語は避け、業務システムの基本的な仕組みから説明する必要があります。スクリーンショットや動画を利用して説明する方が、分かりやすいでしょう。
逆に、業務知識が深い人を対象として考えた場合、なるべく目的を素早く達成できるように、手順を簡潔に示すことが重要です。余計な前提情報を盛り込むと、ドキュメントのノイズが増えてしまいます。目的にたどり着く前に、読むのを止めてしまうでしょう。
文章の目的を最初に示す
文書の目的を最初に書きましょう。最後まで読んで、結局役立たなかった、では意味がありません。読者が最初に目にする部分に、文書の目的を明確に示すことが重要です。
- 誰を対象としているのか？
- 何を得られるのか？
- どのように得られるのか？
社内で共有されるドキュメントはエッセイや小説ではありません。素早く、必要な情報を提供するのが目的です。そのため、最初に目的を示し、その後に詳細を記述するのが効果的です。
情報を簡潔に整理する
情報を簡潔に整理する考え方として、KISS（Keep It Simple and Stupid）の原則があります。これは、情報をシンプルに保ち、読み手が理解しやすくするという考え方です。元々はシステム設計に関係する言葉で、システムをシンプルに保ち続けるのが大事であるという意味です。
ドキュメントであっても、KISSの原則は大事です。ドキュメントは一部作ったら終わりではなく、常にアップデートが求められます。アップデートされず、現状と乖離してしまうと、ドキュメントが間違ったものになります。間違ったドキュメントは、存在しない以上に迷惑なものになります。
一つ一つのドキュメントは分かりやすく構造化され、シンプルになっているべきです。シンプルであれば、更新する工数も小さくて済みます。また、読み手も迷わずに目的の情報を得られるでしょう。
伝わる技術文書の構成と書き方
では、ここからは伝わる文書の構成と書き方について解説します。
- 見出しを活用する
H1, H2, H3 の適切な使い方 - 箇条書きを活用する
リストで要点を明確に - 一文を短くする
冗長な表現を避ける - 日本語として読みやすく
漢字や句読点の使い方を注意 - 視覚的に整理する
表・図・コードスニペットの活用
見出しを活用する
見出しは文書構造の基本です。WordやGoogleドキュメントでも見出しがありますし、HTMLであれば <h1> から <h6> までの見出しがあります。Markdownならば # を使います。見出しを使うことで、文章の構造が明確になり、読み手が目的の情報を素早く見つけられるようになります。
見出しは書いている内に、ついつい深くなってしまいがちです。そのため、見出しの深さはH1〜H3の3つまでにしましょう。それ以上深くなると、読み手が混乱してしまいます。あまり深くなるようであれば、文書の構成自体を一度見直しても良いでしょう（分割するなど）。
箇条書きを活用する
箇条書きはいわゆるリストです。リストを使えば、文章のように冗長的に書く必要がなく、要点を簡潔にまとめられます。また、文章の最初にリストを書き、その後で各項目について説明を加えるのも効果的です。
ただし、リストも見出しと同じく、深くなりやすいので注意しましょう。リストは2段階程度が妥当です。3段階以上になる場合は、見出しに分けたり、文章に展開したりする方が分かりやすくなります。
また、リストは短い言葉で終わりましょう。複数行に渡るようなリストは、逆に読みづらくなります。
一文を短くする
一文を短くすることも大事です。長い文章は読み手にとって負担になります。一文が長くなりすぎる場合は、文を分割するか、冗長な表現を削るなどして短くしましょう。句読点が一文に3回以上入らないようにすると、読みやすくなります。
段落で言えば、2行以内に収まるようにしましょう。主語・述語・目的語の関係が明確になるよう意識すると、短くまとまるようになります。
日本語として読みやすく
句読点や漢字と平仮名の使い分け、敬体と常体の使い分けなど、日本語として読みやすい文章を心がけましょう。「の」や「で」が繰り返されたり、漢字が多用されたりすると、読み手にとって読みづらくなります。
こうした可読性という部分は、記者ハンドブックを参考にしたり、日本語に対応したLinterを用いたり、Microsoft Wordの校正機能を使ったりすると良いでしょう。
視覚的に整理する
文章は、それを読んで頭の中で想像して理解する必要があります。想像する部分は一人一人異なるため、間違った解釈が生まれがちです。そこで、想像を補えるように図表やコードスニペットを活用しましょう。
システムドキュメントであればアーキテクチャ図やクラス図、ER図、シーケンス図などが利用できます。ヘルプドキュメントであれば、画面のスクリーンショットが有効です。コードの説明であれば、コードスニペットを使うと分かりやすくなります。
図表は画像の場合、メンテナンス工数が大きくなります。PlantUMLやdraw.ioを使うなど、コードで管理できるツールを使うと良いでしょう。Googleスライドで作成して、iframeで埋め込むのも一つの方法です。
わかりやすい技術用語の使い方
ここでは、エンジニアの視点で技術用語の使い方について解説します。
- 専門用語の使い方
読者が知っている前提か？ - 略語や社内用語を適切に説明する
初出時に解説をつける - 例を交えて説明する
概念だけでなく具体例を示す
専門用語の使い方
専門用語は、読者が知っている前提で使うか、知らない前提で使うかで使い方が変わります。社内のドキュメントであれば、社内で共通の用語を使うことが多いでしょう。そのため、社内のドキュメントであれば、社内用語を使っても多くの場合は問題ありません。もちろん、オンボーディングの文書であれば、社内用語は避けるべきです。
外部向けのドキュメント（社外の人たちと共有するなど）であれば、前提知識が異なる点を把握しておきましょう。同じ単語であっても、企業によって別な意味で使っているケースは多々あります。
たとえば売上げという単語です。企業によって売上げのタイミングは異なるため、間違った認識で開発が進むと、後で大きな問題になるでしょう。クラウドといっても、スタートアップの場合はパブリッククラウドが前提で、エンタープライズ企業の場合はプライベートクラウドが前提かも知れません。
略語や社内用語を適切に説明する
ドキュメントの中では、略語の使用をなるべく避けるべきです。略語を使う場合は、初出時に解説をつけるようにしましょう。略語を使う場合は、その略語が何を指しているのかを明確に示すことが重要です。
社内用語も同様です。社内用語を使う場合にも、初出時に解説をつけるようにしましょう。社内用語は、社内で共通理解があると考えがちですが、実は部署内だけ、チームだけの擁護だったという場合も良くあります。
読み手ファーストという視点においては、間違った認識をされることは避けるべきです。
書いた後にチェックすべきポイント
ドキュメントを書いた後、ぜひ行って欲しいチェックポイントを以下に示します。
- 誤字脱字がないか？
声に出して読む。Linterにかける - 読み返して伝わるか？
同僚に読んでもらう - 簡潔にできる部分はないか？
冗長な表現を削る
誤字脱字がないか？
誤字脱字が多い文書はとても読みづらく、内容の品質まで疑われてしまいます。一番手軽な方法としては、文書を声に出して読んでみることです。ただ目で追うのではなく、声に出してみることで引っかかる部分が見つけやすくなります。
同様に、Linterを使うのも良いでしょう。Microsoft Wordの校正機能や、Grammarlyなどのツールを使うと、誤字脱字を見つけやすくなります。
読み返して伝わるか？
最低限、誤字脱字がない状態になったら、可読性や理解しやすさを確認しましょう。自分で書いた文章は、前提知識がある状態で読んでしまうので、その理解しやすいさを正しく判断するのが困難です。そこで、他者に読んでもらうことで、読み手の立場に立ったチェックをしてもらえます。
一番良いのは、元々のターゲットである同僚などに読んでもらうことです。これで、読者が理解しやすいかどうかを確認できます。そこでフィードバックを受け、加筆修正を行えば、より品質の良いドキュメントになるでしょう。
簡潔にできる部分はないか？
冗長的な表現を避け、なるべく簡潔で伝わりやすい文章を目指します。この部分においては、ChatGPTなどのLLMが役立ちます。現状の文章を80点として、修正すべき点を指摘してくれ、より読みやすくなった文章を提示してもらえます。
機密性の高い文書や、社内情報統制上LLMが利用できない場合もあります。その場合には、文章を数日置いてみるのがお勧めです。数日置くことで、文章を客観的に見られるようになります。そうすると、分かりづらい部分や、冗長な部分を見つけやすくなります。
まとめ
今回は「読み手ファースト」の観点から、社内ドキュメントの書き方について解説しました。エンジニアの視点だけでドキュメントを書くと、他部署のメンバーからは読みづらい文章だと受け止められてしまうケースが多いようです。読み手ファーストの視点を取り入れ、読みやすいドキュメント作成を心がけましょう。
オープンソース・ソフトウェアのWikiであるGROWIは、マニュアルや企画書の共有、議事録の同時編集など、
チーム内での快適な情報共有と作業効率化を支えるツールです。自社内に立てられるので、機密情報を扱う上でも安心です。ぜひ情報共有促進のために、GROWIを役立ててください。
Discussion