わかりやすいドキュメントを書く方法
2024年3月12日(火)、Asanaのイベント「ツキイチAsana勉強会🧑🎓 #4. Asanaを社内に説明する【LT大会】」のLTに登壇しました。
発表資料はこちらです↓
このLTの目的は
対象者とスコープは
でした。
Asanaを社内に説明する上で、わかりやすさは重要です。
基本的なコツを知っておくと、メールを書くときや議事録をとるときなど、他の多くの仕事でも役立ちます。
LTでは7分程度の持ち時間に合わせて内容を絞っていました。
この記事では、もう少し詳しくご説明します。
はじめに
テクニカルライティングとは、技術的なガイドや説明書を書くテクニカルライターという仕事の考え方であり、決まりごとです。しかし、それらを専門としない一般の方でも、基礎を知って一部を適用するだけで効果を発揮することができます。
背景（読み飛ばしてよい部分）
私は2015〜2016年にかけて当時の勤務先にAsanaを導入したのですが、その際に提案書でも説明書でも「わかりやすさ」を意識しました。「Asanaは簡単」と思ってほしかったのです。
LTイベント後の懇親会で、https://note.com/tatecopter さんに「認知容易性」という概念を教えてもらいました。「理解しやすいことほど好まれる」ということです。Asanaを導入する上で「わかりやすさ」を重視した私のアプローチは、理論的にも正しかったと裏付けられました。
なお、導入時には「スイッチ! ──「変われない」を変える方法」という本でチェンジマネジメントを学び、助けられました。
後に読んだ「ファスト＆スロー」の考え方がベースになっていたようです。そして「ファスト＆スロー」には認知容易性について書かれていました。忘れていた😢
当時は自己流で書いていましたが、のちに以下のQiita記事を読んでGoogleの無料コースでテクニカルライティングを学びました。
それまで感覚的に意識していたことを体系的に言語化できたこともあれば、それまで気づかなかった新たな学びもたくさんありました。
目的と対象読者とスコープを明確にする
さて、テクニカルライティングとは、単に文の書き方を学ぶだけではありません。
読者が何を求めているのかを理解し、情報を整理し、読者のために「わかりやすく」提供するためのすべての姿勢や行動が「テクニカルライティング」です。読者が自分にとって関係のある文書なのかを即座に判断できるようにする必要があります。
このLTの最初にも、目的・対象読者・スコープを明示しました。対象外の経験豊富なテクニカルライターは、ブラウザーバックすることも、目次だけ見て興味のある場所だけ読むこともできるのです。
この点について、サイボウズさんのスライドがとってもわかりやすいです↓
デザインの四大原則
テクニカルライティングの詳細に立ち入る前に、手っ取り早く適用できる考え方をご紹介します。
「デザイン」と聞くと何を思い浮かべますか？
「オシャレにすること？」「色を使うこと？」などと思われるかもしれませんが、「ストーリーを一意に伝える」というポイントが重要です。ユーザーに特定のアクションを促すもの、特定の感情を惹き起こすもの、特定の行動をとりやすくする工夫がデザインです。
受け手によって解釈が変わるもの、わかりやすさに寄与しないものは、デザインではなくアートです。
わかりやすいドキュメントを書くということは、デザインすることに他なりません。まずデザインの四原則を意識してみましょう。
WordでもGoogle Docsでもnoteでも、テキストエディターを使うと自然に以下の3つは守ることができます。
近接 → 近くにあるテキストは一つの段落として認識 (グルーピング) されます。
整列 → 見出しや段落は同じ位置から始まり、同じ長さで改行されます。
反復 → ドキュメントは、「見出し + 段落」の繰り返しで作成されます。
強弱は不足しがちになるので意識して増やしましょう。
強弱 → 見出しは控えめに小さくしがちですが、思い切って大きなサイズにした方が、読み手にとっては読みやすいものです。
テクニカルライティング
それでは、テクニカルライティングを詳しく見てみましょう。
ドキュメントや文章の全体に関わるルールから、各文を書くための細かいルールまであります。どちらにも一貫して共通する目的は、「わかりやすいドキュメントを書くこと」つまり低い認知負荷で情報を伝えることです。
英語のライティングでは、各段落をリードセンテンスで始めるのがよいとされています。その結果、読者は一文目だけ拾い読みしていけば大まかな内容がつかめるようになります。
Googleのコースでは Write a great opening sentence という段落が一番印象に残りました。概ねこのような意味です↓
素晴らしい第一文を書こう
どの段落においても、冒頭の一文が最も重要です。忙しい読者は一文目だけに注意を払い、その後の文を読み飛ばすことがあります。したがって、第一文に筆力を集中させるべきです。
能動態・受動態の使い分けはLTの中で一番大きな反応をいただきました。
以下の二点は、『日本語の作文技術』の主要要素です。
日本語の文章術については『日本語の作文技術』や『理科系の作文技術』などの古典を一度読んでみるのがおすすめです。最近の類書や別のリソース（動画など）を選んでもよいと思います。
画像・動画・イラストを使う
LTで紹介する時間が取れなかったのですが、ビジュアルはかなり大切です。
テキストだけで説明するより、スクリーンショットや動画で手順を説明してみましょう。画像には適切なキャプチャをつけたり、画像中で注目すべきポイントを丸で囲んだりしましょう。
手順の説明時は、画像より動画の方がわかりやすいことがあります。
AsanaのVimeo連携を使えば自分の顔や声と一緒に画面を録画できます。
動画をGIFに変換すれば直接ドキュメントに埋め込むこともできます。私はMacで画面録画したmovファイルを https://cloudconvert.com/ でGIFに変換しています（FPSは20に設定）。
以上、テクニカルライティングの概要をご説明しました。他にも多くのルールがありますが、すぐに生かせる主要なコツに絞って紹介しました。どれも、言われてみれば「なるほど」と思える、読者に寄り添った考え方だと思われたのではないでしょうか。
他の人の目で見直して改善を続ける
どんな文章も、一度書くだけで完成することは稀です。テクニカルライティングでは、読み直して改善を続けることが重要視されています。「完成」後も、読者からの質問を受けたり、運用するにあたり更新が必要になったり、常に更新し続ける必要があります。
ドキュメントを書く人の頭の中では、必要な情報がすべて整理されているので、書いた本人にとって文章の意味は明確です。
しかし、いざ他の人が読むと理解が難しいことも多々あります。
対象読者がどのような前提知識を持っているのか、文章を読み慣れているのかに応じて、わかりにくい部分は改善していきましょう。ドキュメントの公開前に対象読者に読んでもらい、フィードバックをもらうのもいいでしょう。
ChatGPTなどのツールでチェックすることもできます。（プロンプト例: 「テクニカルライティングの観点で改善してください」）
そして、自分自身も別の自分になって読み直すことが重要です。対象読者ならどのような疑問を持つだろうかと想定することも、音読して耳から聞くことも、次の日にフレッシュな目で見直すことも、すべて効果的です。
ドキュメントを書いて数年後に自分で手順に従ってみると、手順がわかりづらく感じることもあると思います。そのため、ドキュメントはPDFなどの固定フォーマットではなく、Google Docや社内Wikiなど、随時更新できる場所で管理していきましょう。
ちなみに（読み飛ばしてよい部分）
今回は、スライド全体を一つのテクニカルドキュメントとして扱い、最初に目的と対象オーディエンスを明示するなどの工夫をしました。わかりやすさを体感していただけたことを願っています。
そして、他の人の目を通したかったので、このLTは当日朝に同僚に練習を聞いてもらい、フィードバックをいただきました。ありがとうございました。
以上、内容が皆様のお役に立てば幸いです！