優れたドキュメントは目的にかなっている　“読む目的”を達成させるために書き手が意識したい「2つの品質」

「優れたドキュメントとは何か」を定義する

岩瀬義昌氏：最後にもう1個だけ。今日は9章までしゃべりたかったので、これをあと5分でしゃべれればゴールですね。ドキュメントの品質測定について話していきます。

（スライドを示して）品質測定、このあたりのキーワードから、きっとエンジニアであれば1度は言われたことがあるんじゃないかという言葉はこれです。

「計測できないものは改善できない」という言葉があります。これはいろいろな引用元があるので（スライドの）後ろに画像を出していますが、計測したいんですよね。というのも、これができていないと行き当たりばったりでプロダクト改善をすることになるので、基本的には何らかの指標で計測をしたいと思います。そのために「そもそもどうやればいいんだろう」「どう計測すればいいんだろう」と考え始めるわけです。

いったん1回だけ立ち戻って考えてほしくて。計測するんだったら何が優れているかを決めていないといけないので、まずは優れたドキュメントというものを定義してからその先に進んでいきます。「優れたドキュメントとは何か」をGoogleのエンジニアたちが言っている言葉があって、これをそのまま引用して本書では使われています。

「ドキュメントが優れているのは目的にかなっている場合である」と言い切っているわけです。これは有名な定義の1つです。

この目的は何かというと実は2つあって、1つがドキュメント自体でユーザーの特定の行動を促進する、推進することです。2つ目が組織のゴールです。これはプロダクトのゴールと言い換えてもいいですね。組織のゴールを達成すること。この2つを満たしているものが良いドキュメントなわけです。

ドキュメントにおける2つの「品質」

この目的をさらにブレイクダウンして考えやすくしていくと次のようになります。ゴールを達成する品質をさらに考えていくわけですね。品質は大きく2つあって、この目的を達成するための品質で重要なのは、先ほど言いましたが1個目は機能品質で、ドキュメントの目的はゴールが達成されているかということです。

今日、しゃべり始めてからずっと「ユーザーの課題は何だ」とか「それは誰の何を解決するんだ」ということを言い続けているんですよ。まさにこれも一緒で、一番測るべきは「ドキュメントの目的はゴールが達成されているか」、言い換えると「ユーザーの価値になっているか」ということになると思います。これが1個目です。

もう1つが構造品質で、ドキュメントそのものにも品質がありますよね。「うまく書けていますか？」と。例えば「てにをは」や、あとはパラグラフの分け方がうまく構成されているかが構造品質になっていきます。

（スライドを示して）それぞれの品質の中身をめちゃくちゃしゃべりたいんですが、時間的に無理なことがわかってきたのでここに羅列していきます。左側が機能品質、右側が構造品質です。左側のほうが先ほど言ったとおりのゴールに近づくやつで、右側が例えば明確・簡潔・一貫性など、文章を書く時に気をつけることですね。

2つの品質を紹介しましたが、重要なのはどちらが（より）重要かというところなんですよ。もうみなさんは答えをわかっていると思います。2つあるんだったら、圧倒的に機能品質（が重要）です。

何度も言っているんですが、どれだけすばらしい文章があったとしても、どれだけ最高のパラグラフ構成だったとしても、ユーザーのゴールの達成につながらなければそのドキュメントは価値がないので、徹底的に機能品質を考えるのが重要かなと思います。なのでそれを意識してドキュメントを書いて、リリースサイクルを回していくのがいいかなと思います。

メトリクスの“絞り込み”が重要

おまけでもうちょっとだけ。品質特性はいろいろなパターンがあるので、他にもあります。例えばドキュメントのメトリクスはすぐに取れるんですよね。特にWebのドキュメントに関してはGoogleアナリティクスなど、いろいろな解析ツールがあるので、PV数やユニークユーザー数や直帰率とか。

あとはTTHW（Time to Hello World）ですね。これはプログラミング言語を使う時に、（その言語が）「Hello World」を出すのにどれだけ時間がかかるかというのを測る時間の指標です。APIであれば最初の一番シンプルなGETを叩くまでとか、そんな感じです。

という感じでメトリクスはたくさんあるので取れるんです。これももちろん品質改善に使えます。ただ、めちゃくちゃ（種類が）あるので「どれを使ったらいいですか？」ということを絞り込んでいくほうがどちらかというと重要です。

たくさん取れるけど、絞り込んで本当に重要なものを使うのであればだいたい活用の計画を立てておくと良くて。「なんでそのメトリクスって重要なんですか？」「さらにその情報を使ったら何ができますか？」「それを使うと組織のゴールはどんなふうに前に進みますか？」という、メトリクスに関しても前段階を考えておくと、より良く効果的に使えるかなと思います。

（スライドを示して）こんな感じで、集め始めるとベースラインが取れます。つまり現状が50点なので、何かしたら次は60点になるというかたちにわかるようになります。メトリクスがあることによって比較ができるようになりますよね。改善が効くというか、論理的にわかるようになるのは、このあたりのパート（の効果）になっているかなと思います。

冗長でくどい日本語を避ける

ということで、時間があったら日本語特有の観点（を紹介する）というところで一瞬だけ紹介します。

冒頭で左下の『理科系の作文技術』（という本など）を紹介したんですが、ドキュメントの本はたくさんあるので、いろいろな本を参照するとどんどんうまくなります。

（スライドを示して）時間がないので（詳しく）紹介はしないんですが1個だけ。ちょっと割愛しますね。僕はこれがけっこう気になる病にかかっているので、最後に1個だけ紹介して終わります。

日本語のテクニカル系の硬い文章を読んでいくと、動詞に「方法」とか「こと」というのを付けて、安易に名詞化しているケースがよくあります。これをやるとけっこう冗長でくどい日本語になります。

わかりづらいのでわかりやすい例を出すと、「機能Aを使用するという方法もあります」みたいな。こうやって書いても良いと言えば良いんですが、これは「機能Aも使用できます」と（すれば）めちゃくちゃシンプルに書けます。

他にも「Bにより改善することができます」。「する“こと”」って付いていますよね。これはいらなくて、「Bにより改善できます」で十分に意味は伝わるので、これを気をつけていくだけで、シンプルで見栄えの良い文章（になり）、しかも読みやすくなるので、このあたりを気をつけておくと良いかなと思って紹介を終えたいと思います。

セッションで紹介した内容のまとめ

（スライドを示して）ということで今日はめちゃくちゃしゃべったんですが、（全体として）こんな感じの概要を今日はしゃべってきました。

書籍の概要をしゃべって、1章で一番重要な（ことは）ドキュメントを書く上では読み手の理解が大事。3章で（重要なこととして）「書く上ではこういうことを考えましょう」というところを伝えてきました。

フィードバックの集め方に関してはこんな方法があって、トリアージする方法がありますねと。あとは「品質って何がありましたっけ？」というところで、機能品質と構造品質。どれだけきれいに書けていても、ゴールが達成されていないと意味がないとか。あとはおまけはしゃべっていませんが、良書がいっぱいあるので見てくださいというところが今日話した内容でした。

ゴールをおさらいしておくと、最初の2分ぐらい（のところ）で、「今日のイベント終了時、30分後にはこんな状態になっていたらいいですね」ということを話しました。

（スライドを示して）上のところが本書の今日のメインのゴールで、ちょっとでもスキルが、（ドキュメントライティングに対する）解像度が高まった気分になっていれば良いかなと思うので、ぜひ実践につなげてもらえればと思います。

今日はしゃべれていない内容が正直いっぱいあって。先ほど言った「良いサンプルコードって何だろう」とかはまったくしゃべっていないので、さらに詳細が知りたい場合は、興味を持っ（てもらえ）たら、本には全部書いてあるので、本を買ってもらえたら僕はうれしいかなと思って、私の講演パートは終わりにしたいと思います。

ということで今日のお話は以上です。ありがとうございました。