開発ドキュメントにおいて多用したい表現の一つは、箇条書きです。箇条書きをうまく使うことで、構造がはっきりとした分かりやすい表現にできます。

 箇条書きの効果を理解するために、図1左の文例を見てください。災害時用バックアップサーバーを障害時に使う方策を見送ることとその理由を書いてあるだけですが、一読してもすっと頭に入ってこなかったのではないでしょうか。

図1●箇条書きによって読みやすい表現になる
文章の中から同じレベルの要素を抜き出して箇条書きにすることで、構造がはっきりとした読みやすい表現にできる
[画像のクリックで拡大表示]

 この文章が分かりにくい最大の原因は、複数の情報を一つの文に押し込んでいることです。これは、文章のなかから同じレベルの要素を抜き出して箇条書きにすることで解決できます。

 ここでの同じレベルの要素は、方策を見送った理由である「サーバーの性能が不十分である」「運用担当者が常駐していないので、切り替え作業を実施できない」です。これらを箇条書きとしたのが図1右です。たったこれだけの修正で、文章全体の構造がはっきりして読みやすくなったことが分かると思います。開発ドキュメントにおける必須条件の一つである「速く読める」を実現する上で、箇条書きは非常に有効です。

 ところがITエンジニアのなかには、「あえて箇条書きを使わない」と言う人がいます。箇条書きでは文章の格調が下がるというのがその理由のようですが、開発ドキュメントの目的をはき違えています。

 開発ドキュメントでは、技術や業務の複雑な仕組みを分かりやすく伝える必要があります。それには、文章の格調より、読みやすさ・分かりやすさにこだわるべきです。その意味で箇条書きは、開発ドキュメントにおいて積極的に使いたい表現手段といえます。

 そこで本講座では、開発ドキュメントで箇条書きを用いる上でのポイントを紹介します。それは次の四項目です。

  • (Ⅰ)箇条書きの前に説明文を付ける
  • (Ⅱ)上位概念を一つにそろえる
  • (Ⅲ)「割り込み箇条書き」にしない
  • (Ⅳ)項目を短く表現する

 今回から四回にわたって、これらのポイントを順に解説していきます。

箇条書きの前に説明文を付ける

 なんの説明もないまま、いきなり箇条書きの項目が並んでいる、という文章を見かけることがあります。書き手は、箇条書きの項目を並べたことで、しっかりと説明できたような気になるのでしょう。

 しかし読み手からすると、いきなり箇条書きを示されても、それが何を表しているのか分かりません。そのため読み手は、各項目の内容を基に、箇条書きが何を表したものであるかを推測しなければなりません。そんな箇条書きでは、読み手にとって分かりにくいばかりか、誤解や認識のズレを引き起こすことにもなりかねません。文例を見てみましょう。

よくある文例①

(1)ソフトA

  • ○○システムと××システムで使用中・近い将来、開発が打ち切られる可能性が高い
  • スマートフォン製品T向けのバージョンは開発中止となった

(2)ソフトB

  • △△システムで使用中
  • 開発はすでに中止されており、サポートの終了時期も発表されている

 何を表した箇条書きなのかが説明されていないので、ソフトAとソフトBとは何か、それぞれの何について書いてあるのかを考えながら読まなくてはなりません。説明のない箇条書きは、読み手にとって苦痛であることが分かると思います。

 箇条書きの前に説明文を付け、さらに項目の分類を付記すると、次のようになります。

修正した文例①

 新ソフトSへの切り替えを検討するため、ソフトAとソフトBの利用状況と新版開発・サポートの見通しについて調査した。

(1)ソフトA
(当社での利用状況)

  • ○○システムと××システムで使用中
    (開発・サポートに関する見通し)
  • 近い将来、開発が打ち切られる可能性が高い
  • スマートフォン製品T向けのバージョンは開発中止となった

(2)ソフトB
(当社での利用状況)

  • △△システムで使用中
    (開発・サポートに関する見通し)
  • 開発はすでに中止されており、サポートの終了時期も発表されている

 説明文によって、新ソフトへの切り替え検討の情報だと分かった上で箇条書きを見れば、すっと頭に入ってきます。カッコ書きで示した項目の分類も分かりやすさにつながっています。なお説明文には、何を表しているのかだけでなく、箇条書きの内容のサマリーや結論を書いたほうがいい場合もあります。

島田 悟志
東京ガスiネット株式会社 デジタル化推進部 インフラ技術グループマネージャー
メーカー子会社にて海外向け電話交換機のプロポーザル作成などを経験後、日本航空に入社。IT本部、運航本部、ロンドンのIT子会社などで勤務。2010年、東京ガスiネットに入社、技術標準化、電力やIoT関連のプロジェクト統括を経て2019年4月から現職。毎年、社内で文章講座を開催しているほか、個別に論文指導も行っている。
上田 志雄
東京ガスiネット カスタマーエンゲージメント部 myTOKYOGASグループ シニアITコンサルタント
1988年、日本国際通信に入社。2003年からティージー情報ネットワーク(現、東京ガスiネット)に勤務。2019年4月より現職。東京ガスグループにおけるITサービス全般の提案・開発・運用・維持管理を担う同社で、会員向けサービス全般の企画・提案・開発を担当。各種クラウドサービスの活用に向けた検証を進めている。
出典:日経SYSTEMS、2012年6月号 pp.68-73 「信頼される開発者の文章テクニック」を再構成
記事は執筆時の情報に基づいており、現在では異なる場合があります。