ユーザーはドキュメントを「読みにくるけれど読んでいない」　“流し読み”しやすいドキュメント作成のポイント

ドキュメントは「書き始める」ことが大事

岩瀬義昌氏：3章にいきます。時間的にあと15分ぐらいしゃべっても大丈夫かな？　10分ちょっとしゃべれると思うので。（スライドが）あと70枚あるので、すごく速くいきますね（笑）。

ドラフトの執筆です。みなさんもドキュメントを書くじゃないですか。ちょっと胸に手を当てて（考えて）みると、ドキュメントを書く上で、一番難しいことは何だと思いますか？　

（スライドを示して）書ける人は良いんですが、最初の人が1文字目を書き始めるのがけっこう大変みたいな。「白紙からの脱却が大変だ」と思う方はけっこういると思うんですよね。これは書籍の中でも「本当に大変です」と言われています。

どうすればいいのかというものがソリューションとして（書籍に）書いてあります。何かというと、一番良いのは手に馴染んでいるツールを使うことで、ドキュメントを書くために何か別のものを有する必要はないです。書きやすいものは人によって違うんですよ。紙とペンでもホワイトボードでも何でもいいので、とりあえず書き始めるのがすごく大事ですね。

別の動画からの引用ですが、スマブラを作っている桜井さん（桜井政博氏）は、とにかく「やれ!!」って言っていましたね。「手が止まったらやれ！　やり始めると動くから」という。これもド正論だなと思ったので紹介だけしておきます。

タイトル・アウトライン・肉付け

書籍の内容に戻ると、ドキュメントを書き始める時に何が重要かということは、もうみなさんわかっていますよね。再三ずっとしゃべっていましたが、「誰が・何のために読みにくるのか」を徹底して意識して書きます。

「そのためにどういうタイプのドキュメントを書けばいいのか」を書ければいいだけなので、これをやれたら（他は）本当に何でもいいんですよ。誰が・何のためにドキュメントを読みにくるかさえ外さなければ良いドキュメントになります。

（スライドを示して）これが意識できているんだったら、実際にタイトルやアウトライン、見出しみたいなものを書いていけばいいわけです。例でいきますかね。「カスタム会話側チャットボットの開発」みたいな。（こういう見出しにすれば）「こんなことをするんだな」ってわかりやすいです。アウトラインであれば、このゴールを達成するにあたって必要なものを見出しで書いておけばいいんですよ。

例えば開発環境の準備手順、あとはAPIの認証方法とかは外のAPIを使うならだいたい使うじゃないですか。「認証してからトークンをもらって叩きますよね」ということが書いてあるのがこのあたりです。

ここまでのタイトルとアウトラインが決まったら、あとはアウトラインに肉付けをしていくだけです。肉付けは見出しや段落、リスト、コールアウトみたいな、いろいろなパターンが使えますよね。

見出しは例えば何かというと、だいたいhタグです。h2とかh3とか、あのあたりです。ドキュメントの道しるべになるので、それを使っておくといいです。意識すべきはユーザーにとってその時に一番知りたい情報を上に書いておくことで、そうするとユーザーは見つけやすいです。

段落は割愛しますが、モリモリ文章が書いてあるところです。一番詳細が書いてあるところです。

あとリストは（入れることで）段落と違ってけっこう読みやすくなります。リストは箇条書きです。箇条書きで読みやすいです。実はリストは本来は順不同ですが、順不同と言いつつも、ユーザーにとって重要な順とかアルファベット順でソートしておくとけっこう読みやすいので、おまけで意識しておくといいかなと思います。

最後にコールアウトです。耳慣れないかもしれませんが、外のドキュメントを読んでいたらみなさんも（すでに）出会っています。

ドキュメントを読んでいくと、カラー背景になっていて、何かちょっと目立つようになっているところがありませんか？　赤字で「Warning」とか。あのあたりがコールアウトです。ユーザーにとっては流れを一瞬断ち切るかもしれないけれど、重要なところを書いているのがコールアウトです。こういうものを使って文章を書いていきます。

それでモリモリ書いていくのはいいんですが、ちょっと悲しい真実が1個だけあります。

ユーザーは「ドキュメントを読みにきている」けれど「読まない」

（その悲しい真実を）お伝えすると、ユーザーは困っているからドキュメントを読みにいくんですよ。ユーザーはわからないから情報を探してドキュメントにたどり着くんですけど、読まない。本当に読まない！　ドキュメントを探して（見に）くるんですけど、読まないんですよ。

（スライドを示して）読まなくて何しているのかというと、こんなふうに目線が移動しています。ユーザーはFパターンでドキュメントを読むということをNielsen Norman Groupの方が見つけて調べていて。このドキュメントの赤い部分があるんですが、これが目線がフォーカスするポイントです。真ん中の部分を見るとわかりやすいんですけど、アルファベットのFっぽい字になっていませんか？

これは何をやっているかというと、見出しを読んで単にザッとスキャンをしていって、中見出しがあったらまたスキャンして読んで、みたいなかたちで文章を読んでいる。（人は）こう読むんだと意識しておくと、いかに見出しが大切かがわかってきますよね。なのでこれを知っておくと良いかと思います。ユーザーはドキュメントを読むために来ているんだけど読まない。だけどこんなふうに読んでいる。

だから書き手としては何をすればいいかというと、「せっかく書いたから読んでほしい」という気持ちはグッと我慢して、ユーザーがなるべく必要な情報をすばやく見つけられるように書いておくのが一番良い。だから流し読みしやすい構成にしてください。するとユーザーにとって価値のあるドキュメントになります。

流し読みがしやすくなるポイント

「では流し読みはどうすればしやすくなりますか」ということが次にきます。それはシンプルで、一番上のところに赤の目線が来ているので、一番重要な情報を最初に書いておけばいいんですよ。手順書だったら一番重要なこと、手順書が完了した時点で何ができているのかを最初に書きます。海外の良いドキュメントを見ているとこれはだいたい徹底されています。

例えば僕はFlutterを趣味でけっこう使うんですが、Flutterのドキュメントを見にいくと、一番真ん中に大きく「What you'll learn」と書いてあるんですよ。「この手順書を読んでやっていくと、これが学べますよ」ということがかっちりと書いてあるので、ゴールがすぐにわかりますね。これは流し読みがしやすくなるポイントの1つです。

あと細かいところで言えば、文章と段落がひたすら続いていくとだんだん壁に見えて辛くなっちゃうので、適切に分割するみたいな細かいテクニックもあります。

（スライドを示して）もう１回Flutterの例でいうと、文章の段落が上にあるんですが、下側に実際に動くようなサンプルの画像があったりして。こんな感じでわかりやすくできますね。これが1つのパターンです。

あとはちょっと細かいので。おまけなので割愛しちゃいます。

いっぱい書いたんですが、もう1個だけこの中でしゃべっていたサンプルコード（について）ですね。ほとんど今日はしゃべっていないですが……。あまりにも重要なんですが、時間がないので割愛します。

（書籍では）サンプルコードだけで1章を出すぐらいという点から、重要なのは伝わるかもしれないんですが、ある研究結果から見ると、人というかエンジニアは、文章の中でもひたすらサンプルコードを探しているそうです。

文章を読むんじゃなくて、サンプルコードを探してから周りを読み始めるような結果が出ているそうなので、サンプルコードをどうやって書くとより価値があるかということを理解しておくと、非常にユーザーの価値につながります。

今日は割愛しますが、（具体的な内容は）書籍を読んでもらうといいかなと思います。サンプルコードはそれ（が理由）で重要でした。

フィードバックの集め方

ということであと10分ちょっとなので、残りにいきます。フィードバックの収集の話をしていきます。

ドキュメントは、リリースしたあとに実際にフィードバックを集めて、仮説検証をしていかないといけません。ドキュメントは出しても使われない可能性もけっこうあります。

（ドキュメントが）使われていないのか、それともバズって使われているだけなのか。あとは何か問題があるのかとかがわからない。機能を出したら基本的に仮説検証をするのは、ドキュメントでもまったく一緒です。ドキュメントはプロダクト機能の一部なので、フィードバックをベースに検証をして、また直していかないといけません。だからフィードバックが必要になりますね。

「フィードバックはどうやって集めたらいいんですか？」という次（の質問）につながってきて。

フィードバックは集め方が何パターンもたくさんあるので、いくつか仕込んでおくと良いかなと思います。（スライドを示して）例をいくつか紹介すると、一番わかりやすいのは、ドキュメントのページにユーザーからフィードバックを募集するフォームを組み込むことです。タグにめちゃくちゃ埋め込んじゃってもいいと思うし、いろいろなやり方があるかなと思います。

あとはサポートチケットにもたくさんありますよね。特にバグを踏んで怒っているユーザーがいた場合は、たぶん相当良い情報が書いてあると思います（笑）。感情が高まっているユーザーのサポートチケットは辛いんですが、宝の山かなと思います。

あとはドキュメントに対する感情ですね。（スライドを示して）この右下のような画像を見たことはありませんか？　これはMicrosoftのドキュメントから持ってきました。「このページはお役に立ちましたか？」「はい・いいえ」とか。これは一種の感情なので、こういうのを集めるのも1つです。

あとはユーザーサーベイですね。これはアンケートみたいなものだと思ってください。最後にもう1個だけ。ユーザーコミュニティ、ユーザー会と言われたりします。特に熱心なグループのユーザーがあったらその人たちでコミュニティを作って、ドキュメントに対して「これ、どう思う？」みたいに率直に聞いてみるのも1つの有用な手段かと思うので、これも理解しておくといいかなと思います。

フィードバックからトリアージする

こんな感じでいろいろな経路を使って情報を集めてくると、たくさんユーザーからのフィードバックが集まってきます。メチャクチャ集まってくる。バグに関する報告とか、いろいろなものがたぶん出てきちゃうんですよ。

なのでQuick Fix、すぐにできるものから、「これ、どっちにしたらいいんだろうな？」みたいな、これから詳細な検討をしたほうがいいような情報まで、いろいろな種類のものが集まってきます。

その集まってきちゃった情報を「そもそもそれって本当に使えるの？」「その優先度ってどうなの？」とトリアージしないといけないです。トリアージはお医者さんや災害現場で使われる言葉ですね。優先度を変えていくみたいなところです。

トリアージするためには、「その課題って有効ですか？」とか「それは本当に直せる課題ですか？」と。あとは「他のIssue報告と混ざっていませんか？」「どれぐらい重要か？」みたいなところを考えていくのが重要です。

（スライドを示して）これではわかりにくいのでKubernetesの例を持ってきたのでちょっと見てみますね。

Kubernetesnのドキュメントを実際に読み始めると……。これは全部しゃべらないんです参考までにスライド中で「次ページでこの辺を拡大します」と書いてあるところをよく見ると、Step Twoのところに「Triage Issues by Type」と書いてあるんですよ。

ここをちょっと拡大するとこんな感じになっています。右側の日本語を読んでみるとわかりやすいです。まず何か報告かフィードバックがあった場合は、「新規のIssueですか」というところを確認していきます。

次にIssueを分類するわけですね。いろいろなパターンがあります。サポートのリクエストだったりバグだったり、いろんな分類があります。そして、本当に直すものは直していくみたいな優先度付けをするのが最後のプロセスです。この3ステップを使ってKubernetesはフィードバックをトリアージしています。

（スライドを示して）優先度付けのところだけをもうちょっとしゃべっておくと、これもドキュメントのページ全部ですがわかりづらいというか。（もともとは）英語なので、日本語にザクッと直すとこんな感じになっています。

上から重要順です。上が超重要なので、今すぐにでも直す。2つ目のところはなるべく早く直せたらいいんですが、次のリリースに乗せればいいかなみたいなものです。3つ目は長期的には重要。4つ目に関しては「これはあったらいいけど、すぐにはやらないな」みたいなものです。5番目は「たぶん」なので、さらに確信がないです。「たぶん有用だけど、いろいろなサポートが得られたのでやる必要がないかな」みたいなのが最後にある感じになっています。

ここまでがユーザーフィードバックの話です。

（次回につづく）