SAKURUG TECHBLOG

皆さんが普段使っているシステムやサービスで、
「どうやって使うんだろう？」「○○機能ってどう設定するんだろう？」
と困ったとき、マニュアルやサポートサイト、技術ドキュメントを読んだ経験があると思います。

私はディレクターとしてユーザー視点でのサービス設計に携わってきた後、今はテクニカルライターとしてプロジェクトに参画していますが、ディレクターの経験は技術ドキュメント作りにも活かせています。

テクニカルライターは元々、家電などの取扱説明書を書く職業でした。ですが、現在はIT企業で仕様書やマニュアルなどの技術ドキュメントを書く役割も多くなっています。

テクニカルライターの観点から、この記事では、「ユーザーにとってわかりやすい技術ドキュメント」を作るための基本的なポイントをご紹介します。

技術ドキュメントだけでなく、日常の文章執筆でも使えるポイントもあるので、ぜひ文章執筆の際に「できているかな？」と意識してみてください。

1．ゴールとペルソナを設定する

何のための、誰向けの文章なのかを設定します。

例えば、サービスを利用するユーザー向けのサポートサイトであれば、
「ユーザーがやりたいことを達成できる」ことがゴールとなることが多いです。

ペルソナに関してはサービスにもよりますが、
「業界知識は豊富だけど、ITリテラシーはそれほど高くない」
「業界知識はそこまで多くないが、開発経験は豊富」など、
ドキュメントを執筆する上でどこを嚙み砕いた表現にするか、
文章の粒度や説明の深さを決めるために設定します。

ペルソナを明確にすることで、必要な情報量や表現の丁寧さが決まり
役立つドキュメントの執筆につながります。

2．用語や表現を統一する

ここでもサポートサイトを例に挙げますが、例えば画面の左側にメニューが表示されていたとします。

そのメニューは何と呼ぶのでしょうか？
メニューバー、サイドメニュー、左メニュー、ナビゲーションなど、
いくつかの用語が思い浮かぶのではないでしょうか。

もしサポートサイト内で、あるページでは「サイドメニュー」、別のページでは「左メニュー」というように
バラバラに表記されていたらどうなるでしょう？

読んでいるユーザーは、「同じものを指しているの？それとも違うもの？別のメニューがあるの？」と混乱してしまいます。

用語や表現を統一することは、ユーザーに不要な混乱をさせないだけでなく、下記のメリットもあります。

• 同じ用語で検索できるため、検索性が向上する
• ドキュメント全体の信頼性が高まる
• 問い合わせ対応時のやりとりがスムーズになる

3．情報を構造化し、探しやすくする

どれだけ詳細に、丁寧なドキュメントを執筆できていたとしても、
読んでいるユーザーが必要な情報を探し出せなければ意味がありません。

必要な情報をすぐに見つけられるよう、情報を適切に整理することも大切です。

• 階層構造を作る
• 見出しを効果的に使う
• 箇条書きや表、図を活用する

見出しは目次としての役割も果たします。
ユーザーが流し読みしても内容が把握できるようにしましょう。

操作の手順であれば番号付きのリスト、設定項目であれば表を活用すると、
よりわかりやすくなります。

4．具体例で理解を助ける

抽象的な説明だけでなく、具体的な例を示すことで、ユーザーの理解がより深まります。

入力例があれば、ユーザー自身に合った内容に置き換えることもできます。
スクリーンショットがあれば、どのボタンのことを説明しているのか示したり、
操作した結果が合っているかなどを確認してもらったりもできます。

まとめ

ユーザーにとって分かりやすい技術ドキュメントを作るための
4つのポイントをご紹介しました。

1. ゴールとペルソナを設定する
2. 用語や表現を統一する
3. 情報を構造化し、探しやすくする
4. 具体例で理解を助ける

技術ドキュメントは書いて終わりではありません。
ユーザーが実際に読んで、理解し、目的を達成するまでがゴールです。

「読むユーザーにとってわかりやすいか？」を意識し、
より良いドキュメント執筆に少しでも役立てていただければ幸いです。