マニュアル執筆が怖くなくなる、12の執筆ポイント：誰にでも分かるSEのための文章術（14）（2/2 ページ）
「提案書」や「要件定義書」は書くのが難しい。読む人がITの専門家ではないからだ。専門用語を使わず、高度な内容を的確に伝えるにはどうすればいいか。「提案書」「要件定義書」の書き方を通じて、「誰にでも伝わる」文章術を伝授する。
業務マニュアルを記述する
7．時間軸に沿って業務の流れを記述する
業務マニュアルは、「業務のどの時点でどうシステムを使用するのか」を伝えるものです。そこで、業務マニュアルは「時間軸」を基準にして表現します。業務マニュアルは、下記のようにして作成しましょう。
- 時間軸に沿って、業務の手順を記述する
- システムを使用する時点において、使用すべき機能を明示する
このとき、単に機能の名称を記述するのではなく、機能を使って何をするのかを具体的に記述します。
8．業務で行う作業を漏れなく記述する
業務の流れを執筆する際に気をつけなければならないのは「業務には、システムを使わない作業もある」ということです。業務の流れには、システムを使用する作業だけでなく（V）、システムを使用しない作業も記述（VI）しておきます。そうでないと、ユーザーはシステムを使うタイミングを判断できません。
V（悪い例）
「注文受け付け」機能の起動
↓
会員番号と暗証番号の入力
↓
会員が認証される
↓
会員情報が表示される
↓
商品名、商品番号、数量の入力
↓
在庫が確認される
↓
注文情報を「センター」に送信
VI（良い例）
会員からの電話を受ける
↓
「注文受け付け」機能の起動
↓
会員番号と暗証番号を聞く
↓
会員番号と暗証番号の入力
↓
会員が認証される
↓
会員情報が表示される
↓
名前、住所、電話番号を会員に確認
↓
商品名、商品番号、数量を聞く
↓
商品名、商品番号、数量の入力
↓
在庫が確認される
↓
商品名と個数を復唱して注文を確定
↓
注文情報を「センター」に送信
9．操作マニュアルと正確に関連付ける
機能の使い方は業務マニュアルに記述する必要はなく、操作マニュアルに任せます。そのため、業務マニュアルは「操作マニュアルのどこを見ればよいか」が分かるようになっていなければなりません。
業務マニュアルで記述する機能の名称と、操作マニュアルに記述してある機能の名前を一致させましょう。マニュアルの作成時や改訂時には、両者に齟齬（そご）がないように確認する必要があります。
10．ユーザー側独特の用語・表現に注意する
業務マニュアルでは、ユーザーが業務で実際に使用する用語・表現を使います。それがユーザーの部署や会社で使われる方言（社内用語、部署内用語）や独特の表現であり、同じ意味で一般に使われている用語や表現とは異なっていても、実際にユーザーが使っている用語・表現を優先して使います（一般に使われる用語は注釈に書いておきましょう）。
正確を期すためには、ユーザーの確認が必要です。用語リストを作成して、ユーザーにチェックしてもらいます。
障害対応マニュアルを記述する
11．ユーザーが障害状況を判断できる表現にする
障害対応マニュアルで最も重要なことは、「発生している障害の状況、現象から対応策を見つけ出せるように記述する」ことです。そのためには、ユーザーがただちに「これだ」と判断できるような表現で、障害発生状況を書く必要があります。
障害発生状況は、次のような要素を用いて表現できます。
- 障害が発生したとき、どのような操作をしていたか
- 表示されるエラーメッセージ
- 障害発生時の画面の状態
- 障害発生の結果、操作はどうなっているか
「画像の変換」機能を使用中に、エラーメッセージが表示され、画面が正常でなくなり、操作不能になる。
上記の例では、使用している機能しか具体的な判断材料がありません。下の例のように、操作やエラーメッセージの内容、画面状態、操作状況を具体的に記述しましょう。
「画像の変換」機能を使用中に、画像データをダウンロードしている途中で障害が発生。変換前の画像の色調が反転し、エラーメッセージ「画像を識別できません」が表示される。別の画像を指定しても反応しない状態が続き、それ以上の操作が不能になる。
12．自力解決できない障害も書いておく
障害対応マニュアルでは、ユーザーが自力で対応できない致命的な障害は、システム管理者やヘルプデスク、または開発側の窓口担当などに連絡するよう記述します。
ただし、そのような障害についても、ユーザーが自力で対応できる障害と同様に、発生する可能性のある機能の個所で、障害状況を記述しておきましょう。対応方法はすべて「システム管理者に連絡してください」となります。
自力で解決できない障害だけを巻末にまとめて、「システム管理者に連絡しなければならない障害の一覧」などとして記述するケースがよくあります。しかし、これではユーザーは対応方法を見つけ出しにくいのです。ですから、その障害が発生する可能性があるところで個別に書いておく必要があります。
著者紹介
谷口 功 （たにぐち いさお）
フリーランスのライター、翻訳家。企業にて、ファクシミリ通信網を使ったデータ通信システム、人工知能、日本語処理関連のソフトウェア開発、マニュアルの執筆などに関わる。退職後、コンピュータ、情報処理、通信関連の書籍の執筆、翻訳、各種マニュアルや各種教材の執筆に携わる。また、通信、コンピュータ関連のメールマガジンの記事、各種雑誌においてインターネット、パソコン関連の記事やコラムなども執筆。コンピュータや通信に関連する漫画の原作を執筆することもある。 主な著作は、『SEのための 図解の技術、文章の技術』（技術評論社）、『ソフト契約と見積りの基本がよ〜くわかる本』『よくわかる最新 通信の基本と仕組み』（秀和システム）、『図解 通信プロトコルのことがわかる本』『入門ビジュアルテクノロジー 通信プロトコルのしくみ』（日本実業出版社）、『図解 ネットワークセキュリティ』『マスタリングTCP/IP IPsec編』[共著]（オーム社）など。
- システム開発を成功させたいSEに送る、「文書執筆のおきて」まとめ
- マニュアル執筆が怖くなくなる、12の執筆ポイント
- 「目次」の良し悪しが、すべてのマニュアルの良し悪しを決める
- 知るだけで天地の差が出る、テスト仕様書の必須項目＆表現方法
- 「バグ数には興味ないのだよ」――顧客が喜ぶテスト仕様書とは？
- 論理的なプログラムを書くプログラマは、論理的な文章も書けるか？
- 文書ごとに最適な「構成のフレームワーク」は異なる
- さらば、翻訳調の文章！ 技術者向け校正ルール
- 専門用語は徹底的に「読み手指向」で書くべし
- 読みやすい文章の極意は「修飾語」にあり
- ドキュメントの質を確実に上げる6つの文章作法
- 「要件定義書のアウトライン作成」完全マニュアル
- 分かりやすい提案書はアウトラインが美しい
- ヒアリング現場で使えるコミュニケーション力
- 開発工程でSEが書く文書の基本
Copyright © ITmedia, Inc. All Rights Reserved.