開発ドキュメントでは、技術や業務の複雑な仕組みを分かりやすく伝える必要があります。その意味で箇条書きは、開発ドキュメントにおいて積極的に使いたい表現手段といえます。本講座で、箇条書きの上手な使い方を学びましょう。
連載
開発ドキュメントの悪文修正術［箇条書き］
目次
-
第1回 箇条書きを使うべき理由
箇条書きの前には説明文を付けよう
開発ドキュメントにおいて多用したい表現の一つは、箇条書きです。箇条書きをうまく使うことで、構造がはっきりとした分かりやすい表現にできます。開発ドキュメントで箇条書きを用いる上でのポイント四項目を紹介します。
-
第2回 上位概念をそろえる
概念が混在すると分かりにくくなる
箇条書きの各項目には「上位概念」があります。これをそろえることが箇条書きで極めて重要です。ここでいう上位概念とは、「目的」「目標」「手段（手順）」「理由」「背景」「問題」「原因」といったことです。
-
第3回 「割り込み箇条書き」は避ける
説明文は箇条書きの前で完結させるべし
箇条書きにしたことで余計に読みづらくなるのでは本末転倒です。ところがそういう箇条書きが、開発ドキュメントでよく見受けられます。
-
第4回 項目を短く表現する
一目で認識しやすいようシンプルに
箇条書きの各項目は、「パラメーターのチェック」のような名詞形（体言）でも、「パラメーターをチェックする」のような文でも構いません。ただし一目で認識しやすいように、短くシンプルに表現します。
