『エンジニアのためのドキュメントライティング』ジャレッド・バーティ

内容

ユーザー調査からのまとめ

ユーザー調査から分かったことをまとめるために役立つ方法が３つあります。

・ユーザーペルソナ

・ユーザーストーリー

・ユーザージャーニーマップ

ユーザーペルソナ

ユーザーペルソナは理想の、もしくは現実の読み手を表現するために作られる半分架空のキャラクターです。

このペルソナは特定の１人をベースに作ってもよいですし、これまでの調査から分かった人たちを合体させた人がベースになっても構いません。

ユーザーペルソナには、（実在であれ架空であれ）個人に対する短い説明があり、そのペルソナのゴール・スキル・知識・状況のリストが含まれています。

ユーザーペルソナを作るために、これまでの調査を通じて理解したユーザーに関する、必要不可欠な特徴をリストにまとめましょう。

ユーザーペルソナを作るときは、ユーザーのニーズを考えてください。

支援を最も必要としているのは誰でしょうか？

ソフトウェアを使うときに最も急な学習曲線を描くのは誰になりますか？

プロダクトの採用を決める上で最も重要なのは誰でしょうか？

ユーザーストーリー

時間に余裕があれば、ペルソナと一緒にユーザーストーリーも作っておくとよいでしょう。

ユーザーストーリーは、ユーザーが達成したいことを短くまとめたものです。

また、今後にやってくる計画・執筆・編集・公開・保守においてユーザーニーズを意識し続けるために、ニーズをまとめておける最適な方法です。

アジャイルなプロダクトチームで働いたことがあるなら、ユーザーストーリーをよく知っているかもしれません。

ユーザーストーリーには、同じフォーマットをよく利用します。

すなわち、「あるユーザー」として「あるゴール」を達成するために、「ある活動」をしたい

というフォーマットです。

調査して分かったことはたくさんの種類の文に分解できます。

また、ユーザー調査の中から重要な部分を１つ抜き取って、それに対する複数のユーザーストーリーを作ることもできます。

ユーザージャーニーマップ

大量の調査ノートやメモが得られる本格的な調査では、ビジュアルによる図解が便利です。

ユーザージャーニーマップは、ユーザーが特定のタスク完了を試みているときに、プロダクトやWebサイトでユーザーがたどった経路を図解したものです。

このマップには通常、ユーザーがソフトウェアやドキュメントに接するときにたどりうるすべての経路、言い換えればチャンネルが描かれます。

ユーザージャーニーマップは時系列になっており、ユーザージャーニー上の各ポイントでユーザーが実施する内容と、各手順におけるユーザーの気持ちやユーザーの体験が説明されます。

ユーザージャーニーマップの作成は、分かったことをまとめるための簡潔な方法であり、ユーザーが最も幸せを感じる箇所と改善可能な箇所を浮き彫りにしてくれます。

ユーザージャーニーマップを作る手順は次のとおりです。

１．ユーザーが達成したいタスクを定義する

２．ユーザーが利用するチャンネルをリストアップする（たとえば、Webサイト、ドキュメント、コードリポジトリ、アプリケーションそのもの）

３．各チャンネルを通じてユーザーが実施する手順をまとめる（たとえば、発見、新規登録、インストール、設定、テスト、実行、レビュー）

４．各手順のユーザー体験をリストアップする（たとえば、何をしているのか、どんな気もちか、何を考えているか）

５．チャンネル、手順、体験を１つの流れで表す

README

READMEは次のような基本情報を含んでいます。

・概要（コードが実行していること）

・インストール方法

・トラブルシューティング手順

・コードのメンテナー

・ライセンス情報

・更新履歴

・基本的な例

・より詳細な情報やドキュメントへのリンク

READMEは簡潔・有益・正確・最新である必要があります。

コードに変更を加えるときは、その変更内容にREADMEが常に追従し続けるようにしてください。

READMEはリポジトリに対するチートシートとして機能するだけでなく、ユーザーが利用する包括的なドキュメントの基礎として機能することがよくあります。

スタートガイド

スタートガイド第一印象と最初のユーザー体験を通じてユーザーを導いていくのが、スタートガイドの重要な役割です。

スタートガイドは、ユーザーの立ち上げを支援する機会となります。

また、良いドキュメントによってユーザーを導きサポートすることで、ユーザーと信頼を築く機会にもなります。

そのスタートガイドを書くときに、自分自身に問うべき質問は次のとおりです。

・サービス内容と核となる機能をいちばん短く説明するなら？

・プロダクトをインストールして使うための最も簡単な方法は？

・新規ユーザーが感じる最も重要な疑問は？

・サービスを使ってできるすごいことはなにか？

手順書

ガイドとチュートリアルを執筆するために、有用なパターンがいくつかあります。

・できるだけガイド単体で読めるようにしましょう。ユーザーが必要とするすべての行動を１つのページにまとめておきましょう。

・必要な手順数は、ユーザーが必要とするものに絞りましょう。たくさんのステップからなる手順は、情報量が多すぎてユーザーは複雑だと感じます。また、長い手順によりミスが起きやすくなり、必要な保守も多くなりがちです。

・長い説明を避けましょう。数行の説明文や適切な配置の画像は効果的です。しかし、手順書内に付加的なコンテンツがあまりに多いと、ユーザーを怯ませてしまいがちです。良い方法は、１枚の標準的なモニター画面で２つ以上の手順をユーザーが見られるように書くことです。手順に説明が多すぎると気づいたなら、コンセプトガイドに情報を分けることを検討してください。なお、これはサンプルコードには当てはまりません。

チュートリアル

チュートリアルとは、特定のゴールを達成する方法をユーザーに伝える手順のことです。

チュートリアルは、ユーザーがコードを実際に書かなくても、組み込みできるかどうかテストするのに役立ちます。

良いチュートリアルには、学習向けにユーザーが使える環境があり、テストデータやツールが提供されていることすらあります。

ドキュメント計画

良いドキュメントの計画は、次を可能にします。

・情報に対するユーザーニーズを予想し、それを満たせるようになる

・方向性に対してユーザーや社内のステークホルダーから早期のフィードバックが得られる

・ドキュメントだけでなく、サービスを含めた全体のユーザージャーニーにおけるギャップと不足箇所を明らかにする

・ドキュメント執筆・構成・公開について、他のステークホルダーと調整する

ドキュメントの計画を作るときは、ユーザーにとって適切な情報に集中するために、次の質問へ回答することが役立ちます。

・対象の読み手は誰か？（すでにユーザーペルソナがあるかも）

・プロダクトのローンチから、ユーザーにいちばん学んでもらいたいことは何か？

・重要度順で考えると、どの機能からリリースされていくか？

・ユーザーはローンチに何を期待しているか？

・ユーザーがプロダクトや機能を使い始める前に必要な事前知識はあるか？

・何のユースケースをサポートしているか？

・ユーザーがつまずきそうな既知の課題や、フリクションはあるか？

見出し

アウトラインにある大まかな手順を見出しにすることで、アウトラインからドキュメントの見出しを作れます。

見出しを作るときは、次の点に注意してください。

・できる限り、簡潔・明確・具体的にしてください。読み手が見出しをざっと読めば、ドキュメントの内容を大まかに理解できるようにすべきです。

・最も重要な情報から始めてください。読み手に最も重要な情報をできるだけページの一番上に書きましょう。

・各セクションで重複のない見出しを使ってください。見出しに重複がなければ、読み手が正しいコンテンツを見つけられるようになります。たとえば、「テスト」というセクションが必要なら、テストされる対象を見出しに追記してください。

・一貫性を保ってください。見出しをすべて同じやり方で構成してください。あるタスクを完了させるための手順書であるならば、見出しをすべて動詞で終えてください。大規模なドキュメントの一部を書いているなら、見出しとスタイルを他のドキュメントと合わせてください。

ドラフト

最終的にドラフトが完成します。

これまでに、読み手が設定したゴールに達するために必要なすべての情報を書き出してきました。

完了したかどうか判断するために、次の質問を自分に問いかけてみてください。

・大見出しはドキュメントのゴールを要約しているか？

・複数の見出しによってドキュメントは十分に要約されているか？

・ドラフトは最初から最後まで読み手のニーズに応えているか？

・情報の流れは読み手にとって理解しやすいものか？

・フリクションログで見つけた課題は解決されているか？

・何らかのドキュメントパターンやテンプレートに正しく従っているか？

・全手順が動作することをテストし確かめたか？

すべての質問に「はい」と答えられたならば、最初のドラフトは完成です。

編集方法

編集時には、改善したいドキュメントの要素の１つに集中するのが有効です。

たとえば、「ドキュメントに書かれている技術情報はすべて正確か？」や「ドキュメントの構成はこれでよいか？」といったようにです。

良いドキュメントにしたいからといってすべての要素に一度に集中しようとすると、扱う対象が多すぎて、進行が遅くなります。

編集プロセスを一連の複数の周回に分解して、１つの周回で１つの編集観点に絞ったほうが、より編集が早くなります。

コンテンツを編集するときに集中すべき要素は、ユーザーと彼らのニーズによって異なります。

しかし、開発者向けのドキュメントのほとんどに対しては、次の観点で編集を周回するとよいでしょう。

・技術的な正確さ

・完全性

・構成

・明確さと簡潔さ

上記の順番で編集することで、開発者が最もよく知っている技術的な正確さから始め、徐々にユーザーが求めているものに進んでいけます（良いドキュメントはユーザーニーズを解決しています）。

これらの各観点で編集をするときは、あたかも初見であるかのように、ドキュメントを読みましょう。

対象のプロダクトや技術をよく知っていると、慣れ親しんだ内容について憶測を生みやすく、新しい読み手にとっての重要な入門情報を軽く扱ってしまいます。

編集プロセスは、そのギャップを埋めて、ユーザーが成功するために必要な情報を追加する良い機会なのです。

フィードバック

良いフィードバックを提供するために、次を実施してください。

・人ではなくアイデアに集中する

・建設的な提案を続ける

・フィードバックに反応するための時間を確保する

フィードバックに関してもう１つ注意点があります。

気に入った部分を伝えてもよいのです。

たとえば、深い技術的なコンセプトをうまく説明できているなら、きちんと伝えて褒める価値があります。

さらに、素晴らしい文章を取り上げることで、他の人が真似できるようになります。

よいサンプルコードの原則

良いサンプルコードは次の原則を満たしているべきです。

・説明されていること：ドキュメントの本文内であろうとコードコメントの中であろうと、必要な場所で背景と説明を加えるために、サンプルコードのそばに説明文が表示されている

・簡潔であること：読み手が必要とする、過不足ない量の情報が提供されている

・明確であること：（読み手が期待する）言語慣習に従ってサンプルコードが書かれている

また実行可能なコードは次の原則を満たすべきです。

・利用可能（であり拡張可能）であること：サンプルの使い方と、読み手自身のデータを入力すべき場所が明確である

・信頼できること：ペースト可能であり、動作し、余計なことを実行しない

フィードバックチャンネル

ユーザーからフィードバックを集める創造的な方法がたくさんあります。

本章の目的に照らし、ここではドキュメントに深く関係する次のフィードバックチャンネルに焦点を当てます。

・ドキュメントページからフィードバックを直接受け取る

・サポートチケットをモニタリングする

・ドキュメントに対する感情を測定する

・ユーザーサーベイを作成する

・ユーザー会を設立する

チャンネルごとに、ユーザーから得られるフィードバックの種類は異なります。

たとえば、ドキュメントページ上でユーザーからの課題を直接受け取ることで、個々のページに対するフィードバックが得られます。

一方で、顧客に定期的に連絡することで、ドキュメントとプロダクトの両方に関するより高いレベルのフィードバックが得られます。

ユーザーサーベイ

１ Corg.lyのドキュメントにどの程度満足していますか？

２探していた情報を見つけられましたか？

３情報を見つけるまでどれぐらいかかりましたか？

４その労力は、予想どおりでしたか？

５ドキュメントを改善するために、何をしたらよいと思いますか？

こういったサーベイによって、顧客満足度のスコア（CSAT, Customer SATisfaction score）を取得できます。

基準値の確立に十分な回答が集まれば、ドキュメントを追加で公開するとき、もしくは現在のドキュメントに挙げられた課題を対応するときに、CSATの変化を追跡できるようになります。

ドキュメントの品質

ドキュメントの品質を次の２つの基本的なカテゴリへと分類しました。

・機能品質：ドキュメントの目的やゴールが達成されているかどうか

・構造品質：ドキュメント自体がうまく書かれているか、うまく構成されているか

機能品質

ドキュメントの機能品質は、ドキュメントが果たすべき目的を達成したかどうかを表します。

根本的なレベルで、ドキュメントが機能しているかどうか調べます。

機能品質全体の測定は困難です。

しかし、ドキュメントの目的により合致しているため、機能品質はより重要なメトリックとなります。

ドキュメントの機能品質は、次のカテゴリに分解できます。

・アクセシビリティがあること

・目的があること

・見つけやすいこと

・正確であること

・完全であること

構造品質

ドキュメントの構造品質とは、ドキュメントがどのぐらいうまく書かれているかどうかを表すものです。

構造品質には、文、段落、見出しの構造、言葉の質、文法の正しさが含まれます。

また、ドキュメントの読みやすさも内包されています。

本書では、優れた文章にある「３つのC」を使って、構造品質を定義します。

・Clear（明確な）

・Concise（簡潔な）

・Consistent（一貫している）

情報アーキテクチャ

最終的にはユーザーのコンテンツに対する期待は次のようになります。

・一貫している：馴染みのある構造とパターンでコンテンツが構成されている。ユーザーはコンテンツの場所が常に分かる

・関連している：最もよくあるユーザーニーズを満たす、最も重要なコンテンツを、最も簡単に見つけられる

・見つけやすくなっている：どのホームページやランディングページからであっても、検索して簡単にコンテンツにアクセスできる

面白かったポイント

技術ドキュメントの原則がまとまっている。

こういうどこでも使える汎用的な原則は早いうちに身に付けておくべき。

満足感を五段階評価

☆☆☆☆☆