システム開発でのマニュアル作成術
私はこれまで小さなものから大規模なものまで、いろいろなウェブアプリケーションの開発に携わってきました。その過程では必ず何種類かのマニュアルを書くことになるのですが、長い間やってきて正確でわかりやすいマニュアルの作成方法が遅まきながらわかってきたところです。
マニュアルは開発中から少しずつ書いていく
マニュアルというのはシステム開発の最後の方にまとめて書くというイメージがあるかと思います。実際、私もずいぶん長い間、納品間近になって慌てて書くようなことが多かったです。
でも、数年前から私はその方法を改めて、一部のマニュアルは開発中から少しずつ書くようになりました。というのも、システム開発ではプログラムだけでなくマニュアルも手を抜かないのページで書いたように、マニュアルは必ずと言っていいほど読まれて、実際にマニュアルに基づいて操作が行われるなど、非常に重要であることがわかったからです。
そして、その重要なマニュアルを書こうとした場合、開発期間が長くなると、最初の方に行ったインストールの方法や設定などは忘れてしまっていることが多く、マニュアルを書く段階になってもう一度確認しなければならない、ということを繰り返してしまっていたからです。
こんなことをしたら二度手間ですし、時間の無駄ですよね。そして、設定が一つでも間違っていると、「マニュアル通りにやっても動かないのですが・・」と、納品後に問い合わせを受けることになってしまいます。
特にインストールマニュアルについては、最初からマニュアルとして書いていっています。面倒だなというときでも、インストールに使ったコマンドやアプリケーションのバージョン、ツール情報、ライブラリなどを書きだすだけでも、随分書きやすくなりますし、正確性も高まります。
記憶というものはすぐに薄れていきます。
インストールした直後は覚えていても、プロジェクトが本格的に動き始めると、すぐに忘却のかなたへと押しやられてしまいます。
保守・運用マニュアルでも同様です。運用の段階になると、ツールを使ったデータ更新などが発生するようになります。コマンドラインツールやGUIツールを使うことがあると思いますが、これらの操作方法も開発と並行して記録していくと良いです。
引数が1つ違うだけで、「ツールが動かないのですが」と、すぐに顧客から問い合わせが入ることになって慌ててしまいます。運用フェーズに入っていると、開発が終わってしばらくたっていることもあります。開発当時の記憶も随分薄れてしまっています。調べようとしても思い出すのに時間がかかってしまい、焦るばかりです。
ウェブアプリケーションの開発ではおかしなデータが入りこまないように、なるべくフォーム入力の段階でチェックするように、マニュアル作成の時もなるべく記憶が鮮明なうちに記録として残しておくと、正確で丁寧なマニュアルができあがります。
操作マニュアルは画面単位ではなく機能単位で作成する
上ではインストールマニュアルと保守・運用マニュアルは開発しながら作成していると書きましたが、操作マニュアルも同じようにするとうまくいきません。
操作マニュアルでは画面のスクリーンショットをとって説明を書く、ということをやりますが、開発段階において画面の変更はよくありますので、せっかくマニュアルを作成しても最後に書き直す部分が増えてしまって効率が悪いです。そのため、操作マニュアルについては、開発が終わって一番最後にまとめて作成しています。
操作マニュアルを作成するにあたってよくあるのが、画面単位で書いていくという方法です。これはとても大事なのですが、これだけだとわかりにくい説明書ができあがってしまう場合があります。
たとえば、ユーザーを登録するという機能はウェブアプリケーションではよくありますが、同時にユーザー情報の変更機能も搭載されていることが多いと思います。
説明書を作るときは、ユーザー操作という大見出しをつけたうえで、ユーザー登録の画面とユーザー情報変更の画面の解説をするとわかりやすくなります。また、目次から探す場合にもとても見つけやすく、ユーザーフレンドリーなマニュアルに仕上がります。
Wordの見出しを活用して目次を自動生成する
マニュアルはWordで作って、最後にPDFに変換して納めることが多いのですが、Wordには便利な機能がついています。それは、目次の自動作成機能です。
たとえば、予算管理システムの操作マニュアルを作成する場合、次のような見出しで作成したとします。
この情報を書く場合、一工夫加えると楽になります。それは、見出し機能を使うことです。
Wordの画面上部には下の赤で囲ったところに見出しを設定する箇所があります。
説明書の大見出しは「見出し１」で、次の小見出しは「見出し２」で書いていくと次のようになります。
大見出しが大きくなって、小見出しも太くなりました。違いがわかると思います。
見出し機能を使うことで何が便利かというと、Wordにはこの見出しを認識して目次を生成してくれるからです。
その方法は、メニューから「参考資料」を選択し、一番左の「目次」を選択するだけです。
そうすると、次のような目次が自動的に生成されます。
とても楽ですよね。
そして、便利なのはマニュアルの修正や追加でページ数が変更になっても、ページ番号を簡単に修正できるところです。やり方は、目次部分を右クリックしてフィールドの更新を選ぶだけです。
とっても簡単です。
私はこれでいつもマニュアルの作成を行っています。
関連記事
１．システム開発ではプログラムだけでなくマニュアルも手を抜かない
２．iPodやiPadに説明書が入っていないAppleの凄さ！
３．プログラマーはユーザーから見える部分に注力しよう
