この前書いたマニュアルの書き方読み方-その1 マニュアルの種類と読み方などなど。。。 の続き。
この前の話では、マニュアルは、大きく以下の4種類に分けられると書きました。
・インストールマニュアル、導入マニュアル等 ・オペレーションマニュアル ・リファレンスマニュアル ・手引書 |
で、その書き方と関連ドキュメントについて書きます。
■インストールマニュアルは、インストール手順をひたすら書く
インストールマニュアルは、インストール手順をひたすら書くしかないです。
このとき、OSがらみのものは、画面キャプチャができないことがあります。
そんなときは、ネット越しに他のマシンからキャプチャしたり、VMWareみたいな仮想マシン上にインストールして、それをキャプチャするとかいろいろあるのですが、
ま、それはともかく、とにかく、手順どおりに書いていき、画面キャプチャして、インストール手順を説明します。
■オペレーションマニュアルは、業務シナリオ+画面定義書
オペレーションマニュアルは、業務手順にあわせて、オペレーション、及び画面入力を書いていきます。ここで、業務手順は、要件仕様(要求定義)の、業務シナリオを作成していれば、それとおなじになります。
作成していなければ、まず、業務手順のシナリオを作成するかんじで、オペレーションを書いていきます。
ここで、詳しい説明を書いていると、なにかいてるかわかんないので、そー言うのを書きたい場合は、手引書か、リファレンスか、付録に書くようにします。そして、基本的には、業務手順のシナリオレベルで書きます。
そうすると、画面操作のところがあると思います。そこに、画面を入れていきます。
画面定義のときに、画面のイメージは作成しているので、それをいれてってもいいってことになります。特に業務シナリオができている場合、オペレーションマニュアルは、画面定義ができた、外部設計終了時点で(コーディングする前に)理論上は作成できることになります(実際は修正が入るのでできないが)
■リファレンスマニュアル
リファレンスは、コマンドラインの関数のような場合は、関数それぞれについて、
GUIの場合は、メニューから選んだ処理1つ1つについて、書くことになります。
関数のようなものは、
・関数名
・概要
・書式
・内容
・引数の説明
・返り値の説明
・例外説明(あれば)
・注意事項(あれば)
などから、構成されます。
一方GUIのほうは、
・メニュー名(操作内容)
・操作方法
・表示される画面の様子と内容
などになります。
■手引書はいろいろ
手引書に相当するのは、一例としては
・システムの開発思想と、システム概要
・他のドキュメントで書き足りなかったこと
・異常系についてなどなど
いろいろあるのですが、まあ、寄せ集め見たいな感じ出し
(ない場合もある)てきとうにかいてくださいませ。
■オペレーションマニュアルとオーバービューなどについて
前にオペレーションマニュアルとオーバービュー、ツアーガイドは同じと書いたのですが、オペレーションマニュアルは、詳しいことが書いてあけど、オーバービュー、ツアーガイドは簡単なケースしか書かない場合があります。
その場合は、手引書でそういう内容をかくか、オペレーションマニュアルからリファレンスにとばして、リファレンスの中で書くなどあります。
■逆引きについて
オペレーションマニュアルと、リファレンスマニュアルの中間として、逆引きというのがあります。これは、操作したい目的ごとに1項目になっている仕様書です。
逆引きがある場合、リファレンスがいらないケースがあります。
ただし、オペレーションマニュアルについては、将来的に引継ぎなんかあったときに、そのマニュアルに基づいて説明すればいい(あるいは、オペレーションマニュアルを読んでもらえばいい)ので、作っておいたほうが無難かもしれません。
ということで、このシリーズは終わりです。