📝

なぜドキュメントを正確に書きたいのか

2023/12/31に公開

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

先日、「ドキュメントを誰のために書いていますか」と「テクニカルライターがプロダクトやチームに貢献できること」という記事を公開しました。

良かったら読んでみてください。

今回は、次世代 Web カンファレンス 2023 Technical Writing セッション (Togetter) では話し足りなかったことの一つ「正確に書く」ことの目的について補足しておこうという記事です。

もしまだ聞いていただいていない方は、こちらからどうぞ！

はじめに

ドキュメントを正確に書くのは、本当に大変です。そしてテクニカルライターをやっておきながらこんなことを書くのもアレですが本当に面倒です。

それでもテクニカルライターがドキュメントを正確に書きたがるのはなぜでしょうか。実はドキュメントを「正確に書く」ことは、単なるテクニカルライターの好みではありません。もちろん仕事だから正確に書かざるを得ない、ということでもありません。

テクニカルライターとして仕事をするうえで「正確に書く」ことにはさまざまな価値があると考えていて、その価値は ユーザーに提供できる価値ではなく、自分が仕事をするうえでの価値 だと考えています。

「自分が仕事をするうえでの価値」を少し違う言葉で説明すると、「正確に書くことで、誰にでも誤りを指摘してもらえるドキュメントになる。そうすると、テクニカルライターがむやみに頑張らなくても誤りがないドキュメントを維持できる可能性が高くなる」ということが期待できるようになると考えています。ちょっと長いので、なんとか短く書くと「正確に書くことで、みんなで品質を維持するドキュメントが作れる」になるでしょうか。

これをなんとか説明してみよう、というのがこの記事です。

正確に書くというと？

この記事でいう「正確に書く」は「誤りを書かない」ではなく、「曖昧に書かない」とか「肝心なところを省略しない」を意味しています。

「誤りを書かない」と「曖昧に書かない」の違い

まずは「誤りを書かない」と「曖昧に書かない」の違いから説明しましょう。

ソフトウェアでは、いくつかのメニューをたどって、目的を達成することがあります。よくある 「ファイルを開くには、[ファイル] メニューを選択してから [開く] を選択します。」 というケースを例に考えてみましょう。

これを 「ファイルを開くには、[ファイルを開く] を選択します。」 と書いたとしましょう。今回の例では、[ファイル] → [開く] の順にクリックすることを説明したいので、この書きかたは明確に「誤り」と言えそうです。これが「誤りを書かない」に反した例です。

では次に 「ファイルを開くには、メニューの [開く] を選択します。」 と書くのはどうでしょう。

この書きかたは「誤り」でしょうか？　ファイルを開くには、最終的には [開く] を選択するので、「誤り」と言い切るのは議論の余地がありそうです。とはいえ、[開く] が [ファイル] メニューの中にあることを説明していないので 「曖昧に書かない」 に反した例と言えそうです。

つまり「ファイルを開くには、メニューの [開く] を選択します。」という文章は、(このケースでは) 「誤りを書かない」は守っています が、「曖昧に書かない」は守れていない と言えそうです。

私は、このような 「曖昧に書かない」を守れていない文章 は、あとあとの作業が面倒になる可能性が高いので、避けたいと考えています。

この記事は、どんな面倒ごとが待っているのか実例を挙げて紹介することで、「なぜドキュメントを正確に書きたいのか」に対する答えが見えてくることを期待しながら筆を進めることにします。

曖昧に書いても困らないこと

実は曖昧に書いても困らないユーザーさんはいらっしゃいます。ソフトウェアの作りがだいぶ一般化してきているからか、ドキュメントを読まなくても操作できます。たとえば、「ファイルを開くときのメニュー」といったら [ファイル] → [開く] と操作することを推測できます。説明が簡単になってありがたいですね。

ということで、実は曖昧に書いてもユーザーは困らないという理屈も十分に成り立ちます。

これを補強するために、ペルソナ (架空のユーザー) を想定してドキュメントを整備しているチームでは、「この曖昧さを許容できるかどうか」を議論して、結論「自社サービスのユーザーは、この曖昧さを許容できるユーザーである」と決めることもできるでしょう。このように決めておくことで、[ファイル] の部分が [File] に変わったり、[アイテム] に変わったりしてもドキュメントを修正しなくて良くなりそうです。これは素晴らしい省力化のように見えます。

が、そうではないという主張をこの記事ではしています。

正確に書くと助かること

「正確に書くと助かること」は「曖昧に書くと困ること」の反対語のつもりです。

実はテクニカルライターをやっていると、「正確に書いておいて良かった～ (曖昧に書かなくて良かった)」と思うことがあります。具体的に助かったケースをいくつか紹介しましょう。

修正対象を絞り込める

仕様変更があったときに、ドキュメントのどこを修正するかカンタンに絞り込めることがあります。

ここで改めて [ファイル] が [アイテム] に変わったケースについて、考えてみましょう。まずは「なぜ」[アイテム] に変わったのか考えてみます。

ここでは説明のために、「開く」対象が増えて、ファイルだけではなく、URI を指定できるようになったことにします。注目していただきたいことは「どのように仕様が変わったか」ではなく、「何かしら仕様が変わった (何かしら取り扱う世界が変わった) からメニューが [アイテム] に変わった」という点です。

(何かしら仕様が変わって) [アイテム] に変わったことで、ドキュメントの修正が必要ないか見ていきましょう。ここでもう一度、私が「曖昧」と書いた説明文を見てみます。

「ファイルを開くには、メニューの [開く] を選択します。」

表示が [アイテム] に変わって開く対象が増えたのですから、「ファイルを開くには」の部分を「アイテムを開くには」とか「ファイルや URI を開くには」に変更する必要があるかもしれませんね。そう、結局、仕様変更があったらほとんどの場合、ドキュメントの修正が必要です。仕様が変わったのにドキュメントを変えなくていい、ということはほとんど起こらないのです。

つまり、『「曖昧」に書くことで「ドキュメントを修正する可能性が減る」』と言うのは難しく、「曖昧」に書いてもドキュメントのメンテナンスは簡単にはならなそうです。

それでは、一体どうすればいいでしょうか。

私は、自分の様々な経験を経て、仕様変更によって何かしら修正する可能性があるのであれば、「曖昧に書くことで修正しなくて済むドキュメント」を目指すのではなく 「正確に書くことで修正内容がすぐにわかるドキュメント」 を目指すほうが合理的だと考えるようになりました。

「正確に書くことで修正内容がすぐにわかるドキュメント」 という観点で、「曖昧」と書いた「ファイルを開くには、メニューの [開く] を選択します。」の文章を振り返ってみましょう。

まずは「曖昧」な文章を修正していく過程を考えていきます。[ファイル] が [アイテム] に変わっているので、ドキュメント全体の「ファイル」を検索して、すべてを「アイテム」に一括置換すればいい気がします。しかし、今回の仕様変更では「ファイル」の抽象度を上げて「アイテム」にしていますから、すべての「ファイル」を「アイテム」に変更することは多少のリスクがありそうです。本当に「ファイル」にだけ関係する文章 (URI には関係がない文章) があったら、「アイテム」に変更しないほうが良いので、その部分では置換しすぎになってしまうリスクがあるというわけです。

ドキュメント全体で「ファイル」は何度も登場しているでしょうから、一か所ずつすべて丁寧に「ファイル」のままか「アイテム」に修正するか検討する作業が必要です。この作業を、正確に推敲するのはかなり難しい気がします。(個人的には、「アイテム」になるかもしれないし「ファイル」になるかもしれないという中立的な気持ちで、すべての「ファイル」を正しく評価するのは苦手です。もちろん、こういった作業が得意で苦にならない方もいらっしゃるでしょう。)

ということで私は「曖昧に書いた文章を修正するのは大変」という主張をしています。

では、[ファイル] とメニューを正確に書いていた場合はどうでしょうか。まず [ファイル] を [アイテム] に一括で置き換えることは、かなり安全そうです。(意地の悪い想像では、ほかの機能で [ファイル] を残したいことがあるかもしれませんが、そのような決断をエンジニアがするのは稀ではないでしょうか。)

次に [アイテム] に変わったページ (つまり限定された範囲) で、「ファイル」を検索し、「ファイル」のままでよいか「アイテム」に修正するかを検討します。このときは「このページでは [アイテム] に変わっているのだから「ファイル」も「アイテム」に変わるはず！」という偏った気持ちで読み直します。実体験として、このケースはかなり正確に作業ができる気がします。

そのあとドキュメント全体で「ファイル」を検索しますが、この時点では「ファイル」の数はだいぶ少なくなっているはずなので、中立的な気持ちで確認しても、正確に確認できる可能性は高くなっていると期待できます。(もちろん、それでも間違える可能性はゼロにはなりませんが。)

ということで、「正確に書くことで、その後の修正作業を正確に行える可能性が高くなる」という例を紹介してみました。これは逆に、「曖昧に書くと、その後の修正作業で間違える可能性が高くなる」と言えるのかもしれません。

誰かに間違いを教えてもらえる

同じ事例を使って、もう一つのメリットも紹介しておきましょう。それは、自分ではない誰かに間違いを教えてもらえることです。間違いを指摘されるのが嫌ですか？　正直に言うと私も好きではありませんが、実はそれほど嫌ではありません。

なぜでしょう。

まず、ドキュメントの目的は「ユーザーに、(ユーザーの) 目的を達成してもらう」ことですね。そのドキュメントに間違いがあったら、ユーザーに目的を達成してもらうことは不可能になります。それではドキュメントの目的を達成しているとは言えません。

そしてシステムの改修によって、ドキュメントはどんどん陳腐化していき、あるとき正しかった情報が間違いに変わっていきます。これを止めるにはシステムの改修を止めてもらうしかありませんが、それはチームの死をも意味することなので止められないでしょう。

そうすると、システムの改修を追いかけて「テクニカルライターが担当するユーザー向けドキュメント」の間違いを修正しなければいけないわけですが…。どこかで聞いたことがある話になってきていませんか？ｗ　システムの改修を追いかけて「エンジニアが担当する仕様書」の間違いを修正しなければいけない話と似ているかもしれません。

さて次の疑問は、どうやったら「システムの改修を追いかける」ことができるか、という点になりそうです。テクニカルライターだけで追いかけることができるでしょうか。これは正直に言って無理、不可能でしょう。なぜなら、すべての改修をすべての関係者 (テクニカルライターを含む) に周知し、それが正しく理解されたことや必要な資料に反映されたことを確認するのは、時間的に不可能だ (と私が考えている) からです。(もしできているチームがあったらぜひシェアしていただきいです！)

ではどうするか…。そう、ここで 「正確に書く」「曖昧に書かない」 が効いてきます。

上で説明した [ファイル] が [アイテム] に変わった例について、もしテクニカルライターに情報が届いてなかったら、だれがいつドキュメントの修正が必要であることに気が付けるか、考えてみましょう。

「ファイルを開くには、[ファイル] メニューを選択してから [開く] を選択します。」 と書いてあった場合、[ファイル] メニューが [アイテム] メニューに変わっていますので、この文章を読みながら操作した人は誰でも簡単に間違いに気が付けそうです。気が付けば、すぐにテクニカルライターに相談できるでしょう。明らかに間違っている、ということが大切です。

「ファイルを開くには、メニューの [開く] を選択します。」 と書いてあったらどうでしょう。本当は「アイテムを開くには、」で始めるべきかもしれません。これが間違っている、とテクニカルライターに相談できる人は多くはないでしょう。たぶんテクニカルライター仲間か、エンジニアくらいです。

どちらがスムーズに「ユーザーの目的を達成するドキュメント」にできるか、私は間違いに気が付ける目が多いほうがいいと思っているので 「正確に書く」「曖昧に書かない」 を守ろうと日々頑張っています。

もちろん、曖昧に書かないといけないこともあって、そういうときは嬉々として曖昧に書くわけですが、そのあたりのさじ加減はまた別のお話しです。

いつも正しく操作できる

書かれている内容が正しいことを確認するのも簡単になります。先程の文章、「ファイルを開くには、メニューの [開く] を選択します。」 を読んで、3 か月後の自分は [ファイル] を選択することを覚えていて、「この文章は正しい！」と確信をもって言えるでしょうか。私は心配です。。。

それから、誰かに原稿が正しいことを確認してもらうときに、「[ファイル] が無いですね」とコメントされたらどうしますか。ひょっとしたら『「ファイルを開くには」と書いてあるから [ファイル] を選択するのは自明で、ペルソナとしてその想像ができる人が想定されているんですよ。ペルソナについては、別のページに書いてあって…』などと説明したくなりそうです。

ただ、このコミュニケーションは、[ファイル] をちゃんと書いておけば発生しない気がします。もっと言うと、「[ファイル] を省略すること」に、いろいろ説明する価値とかペルソナをメンテナンスする価値があるかというと…　どうでしょうか。正確に書いておいたほうが話がいろいろスムーズと言えないでしょうか。

書いた当時に正確に書いたという記憶の大切さ

また、「書いた当時に正確に書いた (ハズ)」という記憶と自信は、さまざまな時間の短縮にとても役に立ちます。仮に、ドキュメントに書いてあることと実際に動作しているサービスに差異が見つかったときのことを考えます。

もし「書いた当時に正確に書いた (ハズ)」という自信があれば、自分を疑うことなく穏やかな心で「ドキュメントと動作が違うということは、仕様変更があったのだと思う。ドキュメントも修正しますね」というようなコミュニケーションができます。ここで大切なのは、「ドキュメントを修正する、という判断をテクニカルライターが自信をもって提示できる」ことです。そう言われるとエンジニアも「はい。現在の動作にあわせて修正をお願いします」と、記憶に基づいて答えるくらいで時間をかけずに終わるかもしれません。(楽観的)

逆に「書いた当時に正確に書いた (ハズ)」という自信がないときは大変です。つい自分を疑って「書いた当時の仕様」を調べたくなることもあるでしょう。どうやって当時の仕様を調べればいいでしょうか？　当時の仕様書を探したり、当時撮影したスクリーンショットを探したり、当時どうしてそのような文章にしたのか証拠探しの旅が始まるかもしれません。長い旅の結果、証拠が見つかればまだいいでしょう。エンジニアに当時の証拠を提示したうえで「当時は正確に書いていたようなので、仕様変更があったのだと思う。ドキュメントも修正しますね。あ、次は変更する前に教えてくださいね☆」と伝えられるでしょう。たぶんちょっとイライラしているので「☆」を付けて自分を落ち着かせたくなると思いますｗ　証拠探しの旅は大変でしたが、エンジニアの時間を奪うことはありません。

もし、証拠が見つからなかったらどうでしょう。ひょっとしたら「いまの動作のとおりにドキュメントを修正してもいいか、本当にチームで合意した仕様変更があったのか、今の動作がバグじゃないのか確認してほしい。もし仕様変更があったなら変更する前に教えて欲しい」という棘のあるコミュニケーションになるかもしれません。エンジニアには、いまの動作が「チームで合意した仕様」と一致していることを確認するタスクが発生しますが、これはコードを読んでも解決できないところが悩ましいですね。

本当は 2 つのもの (今回のケースだと、ドキュメントと実際の動作) の違いが認められたところで、どちらを正にすればいいか相談すればいいので、そんなに複雑なコミュニケーションを取らなくてもいいのかもしれませんが、なぜだか証拠探しに時間を使いたくなってしまうんですよね。私だけかもしれません。そういう時間を減らすためにも「正確に書く」「曖昧に書かない」は効果があると信じています。

参照 (リンク) の話

ついでに参照 (リンク) の話も書いておきましょう。HTML なら <a href="xxxxx">title</a> のようなケース、書籍なら「title」(P.xx) みたいなケースです。どちらも大体同じ話ができるのですが、HTML のほうが体験している方が多いと思いますので、そちらで説明します。

HTML ではとくに title のところに「こちら」と書くことがないでしょうか。「こちら」は、あとで見直すときに本当に大変なので、「こちら」ではなく多少長くなったとしても「なぜドキュメントを正確に書きたいのか」のように参照先のタイトルを書くことをおすすめします。冗長に見えますけど。

ここで説明のために「物理的なリンクエラー」と「論理的なリンクエラー」という二つの用語を導入します。

「物理的なリンクエラー」は、わかりやすく書くと 404 Not Found がでるエラーです。機械的にリンクチェッカーで検出できます。そして「論理的なリンクエラー」は、「そこを参照させて何が分かるんだっけ？」となるエラーです。こちらは機械的に検出するのは難しいです。今なら GPT を使ったら検出できるかもしれません。高くなるけど。

第一に、「こちら」に設定されている URL が「物理的なリンクエラー」を起こしていないことを確認することを考えます。これはとても簡単です。クリックして 404 Not Found がでなければ大丈夫です。

次に、「論理的なリンクエラー」が 起きていない ことをレビュアーが確認するにはどうしたらいいでしょう。起きていないことを確認するのは、リンク元の内容をしっかり理解して、リンク先の内容もしっかり理解するしかありませんのでちょっと大変です。これは「こちら」を使っていても参照先のタイトルを使っていても変わりありません。

一方で、「論理的なリンクエラー」が 起きている ことを確認することを考えてみましょう。もし、「なぜドキュメントを正確に書きたいのか」のようにタイトルが書いてあったらどうでしょう。タイトルが間違っていたら「論理的なリンクエラー」が 起きている 可能性が高いといえそうです。タイトルが変わっているのであれば、内容がかわっていると考えられるので、「論理的なリンクエラー」が起きているいえそう、という論理です。ところが「こちら」と書いているとどうでしょうか。どうやらこの論理は使えそうにありませんね。

実際に「論理的なリンクエラー」かどうかを評価するのはテクニカルライターになるかもしれませんが、そのテクニカルライターに「論理的なリンクエラー」が発生しているかもしれない、と誰でも連絡できる状態にするために、「なぜドキュメントを正確に書きたいのか」のようにタイトルを書く方法は悪くないと思います。ぜひお試しください。

実は「title」(P.xx) のケースでは、特にタイトルを書くことが大切です。書籍で P.xx は絶対に存在するので「物理的なリンクエラー」はほとんど発生しません。「論理的なリンクエラー」は 1 ページ増減するだけで簡単に発生します。論理的なリンクエラーを堅守するためにタイトルを使う方法は、意外と役に立ちます。ちなみに技術的に「論理的なリンクエラー」が発生しないようにする仕組みはいくつもあります。(が、私が知る限りでは完ぺきではありませんね。)

タイトルをちゃんと書いていないと、正しい P.xx が書いてあることを確認することは本当に大変です。以上、面倒でもタイトルを書くことを強くおすすめする理由でした。

ドキュメントを正確に書くことの価値

長くなってしまいましたがまとめると、この記事では、ドキュメントを公開したあとにテクニカルライター以外の人が読んで「誤り」が見つかるようにすることを、いくつかの事例を挙げておすすめしました。

堂々とドキュメントに当時の記録を正確に残しておくことで「ユーザーに、(ユーザーの) 目的を達成してもらう」という目的を達成し続けられるドキュメントにする土台ができあがります。

「誤り」が見つかったときは、誰を責めるでもなく、ドキュメントを正とみなすか、システムを正とみなすか、チームで丁寧に解決していくという考え方は、とても健全なことだと思います。

そして、この考え方はエンジニアが書く仕様書 (内部ドキュメント) にも適用できる考え方だと思っています。「内部ドキュメントが陳腐化して困っているんだよね…」という悩みをお持ちの方は、まず正確に書くことを優先すると、まったく違った世界が待っているかもしれませんよ。

誤りを恐れずに「正確に書く」こと、みんなでがんばってみませんか？