📝

ドキュメントを誰のために書いていますか

2023/12/27に公開

Solo Technical Writer のやざきです。いまは株式会社ソラコムで、SORACOM Users (通称、SORACOM ユーザーサイト) というサイトの管理をしています。「ユーザー」と書いていますがれっきとした公式サイトです。

先日、個人的な立場として (とても大切)、次世代 Web カンファレンス 2023 Technical Writing セッション (Togetter) で議論をさせていただきました。もしまだ聞かれていない方がいらっしゃったらぜひ聞いてみてください。

今回は、そこでは話し足りなかったことの一つ「ドキュメントを誰のために書いていますか」について補足しておこうという記事です。

誰のために書いていますか

「読者のため」に書きましょう。これが原理原則だと思います。

ですが、「読者」を正確に把握できますか？と考えると、現実には難しいことが多そうです。つまり「読者のため」に書くのは難しく、別の誰かのために書くほうがまずは良さそう、というのが私の考えです。

そして、考えられそうな「誰か」は、サポートチーム、エンジニア、プロダクトマネージャー、プロダクトオーナー、自分…というあたりが便利だと思います。「自分」以外は、直接対話ができる誰かを想像するといいでしょう。悩ましいことがあったら聞けば教えてもらえそうです。書いたドキュメントのレビューをお願いできる人を想像して、その人がわかるように書こうとするのもいい方法です。

私は「自分」のために書くことが好みです

私は特に「自分」のために書くのが好みです。これを読んでいる皆さんは「自分」のために書くと聞いて、驚いたことでしょう。ひょっとしたら独りよがりに聞こえるかもしれません。

「自分」と一言で書いていますが、独りよがりな「自分」ではなく、以下の 3 つの帽子をかぶった「自分」のために書きます。それぞれに目的があるので、その目的を紹介しましょう。そして私の場合は、ここで説明する順番で帽子をかぶりなおして原稿を書くことが多いです。もちろん 2 番目の帽子をかぶった後に、1 番目の帽子に戻ったりすることはあります。

ちなみに、この 3 つの帽子をかぶった「自分」が一般に言われる「自分」なのかは、議論の余地があるかもしれません。

ユーザー (主な読者) の代表のつもりの自分

「ユーザーの立場で書く」と表現されることもありますので、聞いたことがあると思います。

ところで、みなさんはドキュメントを書くときに、具体的にどんな「ユーザー」を想像しているでしょうか。よく言われる「20 歳くらいのサトミさん (女性)。スマホは一日中触っているので、ソフトウェアの操作は問題なく行えます。趣味はアカペラ。」のようなペルソナを考えるといいと言われますが、私はあまり得意ではありません。「20 歳くらいのサトミさん (女性)」がどんなつもりでこの製品に出会って、どんな知識レベルでドキュメントを読むのかを想像するのは私にとってはとても難しいのです。

私はそうではなく「XX 機能を使っているユーザー」とか、逆に「XX 機能を使っていないユーザー」のように、知識や経験の有無にフォーカスして「ユーザー (主な読者)」を考えます。これは意外と簡単ですし、効果的です。「XX 機能」の部分は、同製品の別機能でもいいですし、他社製品の機能でもいいでしょう。

「ユーザー (主な読者) の代表のつもりの自分」は、このようにさまざまな知識や経験の有無を考えながら書くときにかぶる帽子です。

この帽子をかぶる目的は、「標準的な手順」と、その手順を実行しているときに「びっくりすること (＝操作しているときに期待を裏切られること)」や「取り返しがつかないこと」をできるだけ書くことです。

「びっくりすること」は、たとえば、「一覧画面で表示される情報でも、詳細画面に表示されないモノがあります」というような内容です。パソコンやスマホを触ったことがあるユーザーなら「詳細画面」ではすべての情報が確認できて、「一覧画面」では概要だけが表示される、ということを期待すると思いますが、期待を裏切る仕様の場合はドキュメントに明記する、という感じで進めます。
「取り返しがつかないこと」は、たとえば「お金がかからないと思っているかもしれませんが、実は追加料金がかかるんですよ。」とか「削除できますが、ゴミ箱はないので取り戻せませんよ。」みたいなことを明記する作業です。

余談ですが、「自社の製品を始めて知った人が新機能を使うときに読む」というケースも考えられなくはないですが、そういうケースは稀だと考えていまして、あまり気にしないことにしています。誤解を恐れずに書くなら「ユーザー (主な読者)」には、「製品を使わない人」「製品をまったく知らない人」「製品に興味を持っていない人」は含みません。そういう人は、基本的にはドキュメントを読みません。ひょっとしたらドキュメントを読むことがあるかもしれませんが、ドキュメントを読むころには、知り合いに「～っていうサービスがあって、こういうところがあなたの役に立つと思うから使ってみたらいいと思うよ」というようなことを聞いたり、同じようなことを SNS や Web で情報を得たうえでドキュメントにたどり着くはずで、もしそうなら「製品をまったく知らない人」を卒業していると思うのです。

製品を使わない人に向けて、細かすぎて、逆に読まなくなってしまう人もいるかもしれません。製品が狙うユーザーにしっかり伝わるように、細かすぎず大雑把過ぎず、ちょうどいいところを狙いたいところです。

エンジニアの代わりのつもりの自分

エンジニアはドキュメントを書くことが得意ではない、とよく聞く気がします。確かにドキュメントを書くことが得意なエンジニアばかりになってしまったら、テクニカルライターは仕事が無くなってしまうでしょうｗ

そんなエンジニアの代わりのつもりでドキュメントを書くことも必要です。ここでは、新機能についてすべてを知り尽くしたエンジニアのつもりになります。エンジニアに仕様書を用意してもらえれば、その仕様書を全部分かったつもりで書きます。たとえば、何かしらの情報を入力するときに、入力できる文字数や使える文字に制限があるかどうか、操作する順序に決まりがあるか、みたいなことを考えます。エンジニアは、その新機能に関わるすべてを知る立場にいるはずなので「私はすべてを知っているはずなのに、文字数制限は書いていないぞ」とか、「UI で項目を選択するときに、項目の違いがすべて書いていないぞ」とか、「すべての画面について書いていないぞ」といったことを考えるときにかぶる帽子です。

それから「わかりやすいかどうかはわからないけど、仕様を正確に書いてあるか」を考えるときにもこの帽子をかぶります。

つまり、この帽子をかぶっているときは、「新機能を利用するうえで、必要なことを網羅的に書けているか」「仕様を正確に説明できているか」を考えながら書きます。

一方で、新機能を開発するために必要なすべての情報をユーザーに伝える必要はない、というのはエンジニアもテクニカルライターも理解しているとおりです。すべてを書けばいいというものではありません。「書くか書かないか」を判断するときに、ひょっとしたら「ユーザー (主な読者) の代表のつもりの自分」の帽子や「3 か月後の自分」の帽子が役に立つかもしれません。

また、エンジニアも、新機能をできるだけわかりやすく (魅力的に、正しく使えるように、などの様々な修飾語) 説明したいと考えているという前提は忘れないようにしましょう。

3 か月後の自分

3 か月後の自分は、すべての操作やその機能を使ううえで大事な概念を正確に覚えておくことはできないでしょう。3 か月後の自分がドキュメントを読むと、3 か月前の記憶が鮮やかによみがえるように書きたいですよね。そのときにかぶる帽子が「3 か月後の自分」です。

たとえば、3 か月後の自分が操作で躓かないように、操作を正しく精緻に書いておくといいでしょう。精緻に書いておけば、仕様変更があったことに気が付けるのでとても便利です。精緻に書いてさえいれば、ドキュメントに書いてある通りに操作してみて、その通りに操作できなくなったら仕様変更があったと判断できますよね。逆に精緻に書いていなければ、当時の自分のミスなのか、それとも仕様変更なのかを調べるところから作業が始まるのでちょっと大変です。

それから、記憶力に自信がなければ (自信がないフリをするのでもいいですね)、3 か月後でも思い出せそうな平易な表現を使ったり、キーワードをしっかり定義するところから書いておくのもいいでしょう。係り受けが難しい表現は、書いたときは最高にわかりやすいと思っていても、3 か月後の自分がスラスラ理解できるかは怪しいです。テクニカルライティングでよく言われる基本的なテクニックは、ほとんどが「3 か月後の自分」が読んでスラスラ読めるかという観点で有効なものと言えるかもしれません。

「一文一文がわかりやすいか」「説明の流れはわかりやすいか」という観点で文章を書くときに「3 か月後の自分」の帽子が役に立つでしょう。

最後に

ドキュメントを誰のために書いていますか？という問いに対して、「ユーザー (主な読者) の代表のつもりの自分」「エンジニアの代わりのつもりの自分」「3 か月後の自分」を考えながら書くのが、思いのほかいい方法ですよ、ということを書きました。

最後に誤解が無いように書いておきますが、それ以外の方法を否定する意図はありません。ペルソナを考えたうえで、その人が理解できるドキュメントを書くのもいい方法です。サポートチームのために書くというのもいい方法ですね。

どのような方法で書いたとしても、正確なドキュメントがあることがとても大切です。「正確で読みやすいドキュメント」が最高であることは議論の余地はないと思いますが、次点は「正確で読むのが大変なドキュメント」だと私は思っています。次は「曖昧だけど読みやすいドキュメント」、次に続くのは「曖昧で読むのが大変なドキュメント」だったり、もっと悪いと単に「不正確なドキュメント」だったりするのではないでしょうか。

「正確で読むのが大変なドキュメント」は、「正確」といえればたどり着ける場所です。2024 年も、3 つの帽子をかぶりつつ「正確」なドキュメントを書いていこうと思います。

この記事が誰かの助けになると嬉しいです。