連載
» 2010年10月19日 00時00分 公開

誰にでも分かるSEのための文章術(14):マニュアル執筆が怖くなくなる、12の執筆ポイント (1/2)

「提案書」や「要件定義書」は書くのが難しい。読む人がITの専門家ではないからだ。専門用語を使わず、高度な内容を的確に伝えるにはどうすればいいか。「提案書」「要件定義書」の書き方を通じて、「誰にでも伝わる」文章術を伝授する。

[谷口功,@IT]

 前回「『目次』の良し悪しが、すべてのマニュアルの良し悪しを決める」に引き続き、分かりやすいユーザーマニュアルの作成ポイントを説明します。前回は「構成」について説明しました。今回は「表現方法」についてです。

 「操作マニュアル」「業務マニュアル」「障害対応マニュアル」 について、全部で12のポイントを解説します。

操作マニュアルを記述する

1.読み手に分かりやすい流れを考える

 ユーザーが操作マニュアルから知りたいことは「操作手順」と「操作の結果」です。

 操作マニュアルでは、これらの情報を、「画面のイメージ」と「説明文」の組み合わせで表現します。

  • 操作手順
    • ユーザーが操作する画面
    • 操作手順を説明する文章

     

  • 操作の結果
    1. 操作の結果を表示する画面
    2. 処理内容や操作結果を説明する文章

 ただし、一般的にシステムの操作は、次のような流れになります。

 表示されている画面で操作を行う
 
 結果の画面に遷移し、新たな画面が表示される≫
 
 表示されている画面で次の操作を行う
 
 

 このように、「前の操作の結果画面=次の操作を行う画面」となります。ここで、操作マニュアル記述の良い例と悪い例を見てみましょう。

I(悪い例)

データの一覧画面で、[閲覧]をクリックします(「操作Aの手順」説明文)

zu01

 すると、データの詳細が表示されます(「操作Aの結果」説明文)

 コメントを入力して[確認する]を押します(「操作Bの手順」説明文)

zu01

 プレビュー画面が表示されます(「操作Bの結果」説明文)

II(良い例)

zu01

 データの一覧画面で、[閲覧]をクリックします(「操作Aの手順」説明文)

 データの詳細が表示されます(「操作Aの結果」説明文)

zu01

 コメントを入力して[確認する]を押します(「操作Bの手順」説明文)

 プレビュー画面が表示されます(「操作Bの結果」説明文)

2.操作手順は「画面→説明文」で書く

 I(悪い例)のように「操作手順の説明文→操作を行う画面」にすると、ユーザーは、まず抽象的な文章を見ることになるため、内容をすぐに把握できません。

 操作手順は、II(良い例)のように「画面→説明文」の順にすると分かりやすくなります。ユーザーには、まず操作する画面を視覚的に把握してもらい、同時に表示画面と比べて相違ないことを確認してもらいます。そして、文章を読ませるようにするとよいでしょう。

3.操作結果は「説明文→画面」で書く

 一方、操作結果はIIのように「結果の説明文→結果の画面」の順で記述します。

 Iのように「画面→説明文」とすると、「操作を行う画面=前の操作結果の画面」の直後に説明文が続かないため、手順を直感的に認識できにくくなるためです。

4.操作手順と結果説明は、明確に分離して記述する

 上記のような方法でマニュアルを作っていくと、「操作手順の説明文→操作結果の説明文」が続きます。このとき、操作手順の説明文と結果説明の文章は、一目で区別がつくように記述しなければなりません。

「顧客」メニューで「顧客情報修正」を選択します。「顧客情報」画面が表示されます。



 

「顧客」メニューで「顧客情報修正」を選択します。

「顧客情報」画面が表示されます。


 文章を続けてしまうと、どこまでが手順で、どこからが結果か一目で判断できません。そのため、手順と結果の文章の間に1行空けるなどして、明確に区別できるようにしましょう。

5.すべての画面をきちんと記述する

 例えば、何らかの処理が終了すると「OK」ボタンだけが表示され、それをクリックすれば次の処理が始まるような場合、IIIのように結果画面を省略しがちです。これは、エンジニア側が「ちゃんと画面に表示されるのだから、見れば分かるだろう」と考えてしまうためです。

 しかし、システム操作に慣れていないユーザーには分かりにくい表現であり、不親切です。エンジニアにとっては煩雑に思えるかもしれませんが、IVのように、きちんとすべての画面を記述しましょう。

III(悪い例)

zu01

 処理対象を選択して、「実行」をクリックしてください。

 処理Aが実行されます。 処理が完了したら、「OK」をクリックしてください。

 処理Bが実行されます。

IV(良い例)

zu01

 処理対象を選択して、「実行」をクリックしてください。

 処理Aが実行されます。

zu01

 処理が完了したら、「OK」をクリックしてください。

 処理Bが実行されます。

6.主語はユーザー? システム? 主語の表現を区別する

 システム操作では、動作を行う主体は「ユーザー」と「システム」、2つあります。ユーザーが操作を行い、システムは処理や画面表示を実行します。つまり、操作マニュアルでは「ユーザーが主語の文章」と「システムが主語の文章」を併記することになります。

 操作手順の説明文はユーザーが主語に、操作結果の説明文はシステムが主語になります。そこで、文章の主語を判別できるように表現する必要があります。

パーツ一覧からパーツの名称を選択して、「OK」をクリックします。

(主語:ユーザー)

指定パーツを本体に貼り付け、イメージ画像を表示します。

(主語:システム)


 上記の例では、2番目の文章の意味が分かりにくくなっています。ユーザーがパーツを貼り付けて、画像を表示するのでしょうか?

 マニュアルでは、主語をきちんと判別できるように表現しなければなりません。「主語を記述する」方法も考えられますが、マニュアルのすべてに主語を記述すると、読みにくくなってしまいます。

 そこで、操作手順の文章(主語:ユーザー)は能動態で記述し、結果表示や処理の実行を説明する文章(主語:システム)は、ユーザーから見て受動態にします。

パーツ一覧からパーツの名称を選択して、「OK」をクリックします。

指定パーツが本体に貼り付けられ、イメージ画像が表示されます。


       1|2 次のページへ

Copyright © ITmedia, Inc. All Rights Reserved.

RSSについて

アイティメディアIDについて

メールマガジン登録

@ITのメールマガジンは、 もちろん、すべて無料です。ぜひメールマガジンをご購読ください。