ドキュメント書きのコツを自分なりにまとめてみる２

前回に引き続き，今度は↓からピックアップして自分なりに解釈してみる．
参考サイト：ほんのすこし書き方に注意すれば、あなたのドキュメントはさらに分かりやすくなる！

さて，スタート．

ユーザーマニュアルにも、入れるべき要素があります。タイトル（見出し）、概要、説明手順、補足情報などです。（略）これらの構成要素であるパーツをきちんと揃えること。これが大切です。

レポートだったら，「背景」「目的」「考察」とかのパーツが増えるんだな．

続いて「概要」について．

「概要」は、その機能が何であるかを伝えたり、作業全体についてまとめたりしたものです。いわば、読み進める前に全体を俯瞰する全体図のような役割を果たすパーツです。

概要は、そのページで何を伝えたいのかを、簡潔に伝えることが役割です。ですから詳細については書かず、全体をざっくりとまとめることが大事なポイントなのです。分量としては、通常は100〜200文字程度でまとめます。

全体を把握してもらうってことなら図もあるといいかも．概要に限らず文章だけではイメージしづらいのでポイントとなる図も織り込む．

注意点は．

こんな機能概要を読んだことはありませんか？
　　* 唐突にこんな細かい説明をされても理解しづらいなぁ。
　　* これじゃ、いったい何ができるのかわからない…。
　　* 制限事項が書き並べられているけれど、こんなに制限があるのかな？

背景はユーザーにとっては、必ずしも重要ではありません。「どうしてこのようになったかを知った方が、理解が深まるだろう」と親切心から書いてしまいがちですが、その機能全体が何であるかを理解できない状態では、かえってノイズになってしまうことがあります。 初めて知る多くの情報を、人は一度に処理できないからです。

• 概要であっても「全体から詳細へ」
• 専門用語は控える
• 背景や経緯も控える
• てんこ盛りにしない

次は「操作手順」について．

操作手順を分かりやすく書くための2つのポイント
　　* 1文1手順に分ける
　　* 操作手順と結果は分けて書く

なるほど．

○ 1文1手順に書き直した例
　　1. 削除したい文字列の最初と最後の文字をクリックして範囲指定します。
　　2. ［メニュー］ボタンを押して、［削除］を選択します。

あー，どこかで見たことがある感じ．

○ 操作と結果を分けて書き直した例
　　1. ［メニュー］ボタンを押して、［設定］を選択します。
　　　　セキュリティレベルの設定についての確認メッセージが表示されます。

　　2. 「高」「中」「低」のいずれかのセキュリティレベルを選択して、［はい］をクリックします。
　　　　セキュリティレベルが変更されます。

あー，これもどこかで見たことがある感じ．普段目にしているくせに書けない…．
とりあえず，これに忠実になることから始めよう．