技術系マニュアル作成の基礎知識

ハッピーホリデー！ということでさくらインターネット Advent Calendar 2019、記念すべき(?)最終回を担当する大井と申します。

今回は「技術系マニュアル作成の基礎知識」と題して、これまでの(どちらかというと開発寄りな)執筆陣のテーマとは違い、プログラミングやコマンド操作ではない自然言語が主体となる「マニュアルのつくりかた」をテーマに、みなさんにその基礎的なテクニックをお伝えしたいと思います。

マニュアルは製品そのものと同じくらいに重要だ

私の最近の中心業務はさくらのクラウドというIaaS型のクラウドサービスに関わる文書全般の作成や整備です。例えばサービスの使い方を記載したマニュアルを作ったり、最近のアップデート情報を中心にブログ形式で告知するクラウドニュースを書いたり…。さくらのクラウドでは高頻度に新機能の追加や既存機能の刷新を行っており、日々のアップデートに遅れることなく追従するドキュメント周りの更新が欠かせません。

さて、さくらのクラウドのようにインターネット上で操作可能なサービスでは、開発元各社がマニュアルを一般公開し、実際に製品を利用せずとも読めるようにしているケースが多く見られます。これは実際にサービスを使う前にマニュアルからも製品評価を導入検討者に行ってもらうためという理由もあるでしょう。マニュアルはサービスを利用中の顧客に対してだけではなく、目立つ見た目でサービスを売り込む販促用のサイトと同様に購入前の参考にされる重要な商材であり、また、契約を獲得した後も顧客満足度に関わる骨子となる部分でもあります。今やマニュアルの良し悪しは売り上げにも関わる見過ごせないポイントになっているのです。

そこで、そんな自然言語ばかり扱っている自分なりに「マニュアルの作り方」で気を付けていることを挙げていきたいと思います。別に企業内でマニュアルを作成する担当でなくとも、個人が開発するサービスなどで自分以外の人に向けた簡単な手順を作る必要があるかもしれません。そんな時にちょっとでも参考になっていただければ幸いです。

マニュアルを書く上での大原則

先にも挙げたセールス用のツールのひとつであるという考え方ももちろん重要なポイントですが、私の中では以下の2点を心がけてマニュアル作成に臨んでいます。

まずマニュアル、いわゆるトリセツには

製品の手順や機能、想定される問題への対処法など、運用する上で必要な事項を余すことなく書いてある文書

という、マニュアルをマニュアルたらしめる当然のお約束があります。これは実際に文書の打ち込みをしている最中だけでなく、事前に構成案を練る時やひととおりの草案執筆後の推敲時など、マニュアル作成に関わっている時間は常に念頭に置いてる原則です。そしてこれを踏まえた上での第2の目標が

サポートコストを低減させる

というもの。これはつまるところ「マニュアルを読むだけで疑問が解ける」ということです。「このボタンはなに？」とか「こういう操作したら動かないんだけど？」といった疑問が発生した場合でも、マニュアルを見ればすぐに書いてある場所を見つけられて疑問が解決できる状態を指します。

マニュアルだけで疑問が解けないと大変なことに

それでも分からなかったら電話やメールでのサポート窓口への問い合わせとなる訳ですが、利用者がそれらの2次サポートに移行してくれればまだいい方で、そのまま解決できなかったからと機能やサービス利用を中断してしまう場合も少なくありません。メールや電話でのサポートが万全なら…という考え方もありますが、サポート要員の稼働に必要な人的・時間的コストは莫大なものになりますし、そもそも利用者がマニュアルでは分からなかったからとサポートに問い合わせるまでのアクションが重すぎます。そうしたサポートに関するコストは決してサービス提供者側だけが被るものではなく、利用者側にも負担を押し付けてしまうものなのです。

製品そのものがいくら優秀でも、マニュアルの品質が低ければ利用者側の評価も低くなるでしょう。そういった意味でも「マニュアルを見れば分かる」という状態にドキュメント整備することは製品の開発と同じくらいに重要な工程なのです。

マニュアルに書く内容

では基本がわかったところで、具体的にマニュアルにどういった項目を書けばいいのかについて説明します。

最近のインターネット上で動くサービスは、PCやスマートフォンのブラウザがインタフェースとなって動作するものがほとんどかと思います。例えばコントロールパネル。入力フォームには枠で囲まれたテキスト記入欄やラジオボタン、リスト選択などの部品があります。それは現実の世界でも良く見かける質問内容が羅列されたヒアリングシートや機械類の設定ボタンを模倣しているわけです。つまり、コンピュータ上で仮想的に表示されるGUIを操作するものであっても、一般的な家電製品と同様のマニュアルとして仕上げるつもりで作成すると分かりやすいかと思います。

電気ポットを例に

では普通の家電製品ではマニュアルにどのような内容で書いてあるかを考えてみましょう。ここでは水を入れてお湯を沸かす「電気ポット」を例に考えていきます。

• 表紙(目次)
• 注意事項
• 各部の名称
• ボタン操作→機能
• 故障かな？と思ったら
• 仕様

こんな感じではないでしょうか。さくらのクラウドのようなインターネットで動くサービスでもこれとほぼ同様です。

• ひととおりマニュアルを読んだ後にリファレンス的に利用する場合に便利な目次
• 「これらのOSやツール、開発環境がインストールされている必要がありますよ」など具体的な利用をする前に真っ先に書いておかないといけない注意事項
• コントロールパネル画面に表示されるボタン類の説明
• GUI上のボタン操作を起点に各機能が動作する一般的なイベントドリブン型製品であればボタンと対応する機能の説明でわかりやすく
• 手順通りの複数操作が必要な機能など、つまづきやすい箇所は「よくある質問と回答」にまとめる
• ネットワークであれば接続数、データ処理であればトランザクションの最大許容数など、利用環境の目安となるスペック

あたりで置き換えると分かりやすいのではないでしょうか。とにかくその製品の機能を余すことなくマニュアルにまとめることが重要です。マニュアルに書いてないボタンがあったり、それが元で誤動作につながったらサポート窓口が賑やかになる事請け合いです。

図版の例

図版についても闇雲に取り入れるのではなく、ここでも家電製品のマニュアルを例に、図版が出てくるのはどういう項目かを考えてみます。

• テレビの接続端子の場所や接続先
• 冷蔵庫の温度調整ダイヤルの位置
• 掃除機で吸ったゴミの回収方法など物理作業

あたりでしょう。こちらも同じくGUIであっても「このボタンを押せばこうなる」とか、「この機能はここをダブルクリックして」など、文字だけでは説明しづらい部分は図版を入れると分かりやすいです。完全にブラウザでの操作となるさくらのクラウドではコントロールパネルのスクリーンショットを多用し、説明箇所を赤枠で囲ったりして説明することが多いです。

まとめ

今回はごくごく簡単に、マニュアル作成の基本的な心掛けや大雑把な記載事項について説明してみました。よくある「コンピューター」とかの長音表記はどうするんだとか「インタフェース？インターフェイス？」みたいな書き方の揺らぎとか敬体か常体かといったことももちろん重要ですが、まずは「マニュアル」というものがどれだけ重要なもので、どういった要素が必要なのかがお伝えできたのであれば嬉しいです。私も「いいマニュアルは世の中を良くする」という信念で、これからもよいマニュアル作りを追求していきたいと思ってます。

それではみなさんよいお年を！

おまけ

ここからはおまけです。インターネット上で展開するサービスでは例としていくつかのIPアドレスやドメイン名を使って設定作業を説明するとわかりやすい、なんて場面もよくあります。でも！よくある「domain.ほげほげ」みたいなドメイン名とか「210.224.＊.＊」といった国内で良く見るIPアドレスは実際に利用されている可能性もあるので使わないようにしましょう。以下のように各管理団体がちゃんとドキュメント内で使える例示用のものを確保しているので、こちらを使うようにしましょう。

例示用IPアドレス

IPv4

RFC5737に規定のDocumentation Address Blocksを使用

ネットワーク名	IPアドレスブロック
TEST-NET-1	192.0.2.0/24
TEST-NET-2	198.51.100.0/24
TEST-NET-3	203.0.113.0/24

IPv6

RFC3849に規定のDocumentation Address Blocksを使用

2001:DB8::/32

例示用ドメイン名

gTLD

RFC2606に規定のDocumentation Examplesを使用する。予約されているものは .test や .invalid などがあるが、ドキュメント用として推奨されているのは .example 。

gTLD セカンドレベル

RFC2606に規定のReserved Example Second Level Domain Namesを使用

• example.com
• example.net
• example.org

jpドメイン

JPRSのよくある質問ページ内「例示に使用可能なドメイン名はありませんか？」に例示のドメインを使用する。汎用.jp、属性.jpそれぞれの example.* の他、数字を含むドメイン名も利用可能で

• example.jp
• example.ne.jp
• example3.co.jp
• ドメイン名例.jp
• xn--eckwd4c7cu47r2wf.jp (「ドメイン名例.JP」をpunycodeエンコードした文字列)