読む人が短時間で理解するためのドキュメント作成3つのヒント

本記事は「2011年4月」に投稿したブログ記事を再編集したものです。

 見せ方・伝え方によって受け方は大きく変わる

同じもの(こと)であっても、見せ方・伝え方によって相手の受け方は大きく変わってきます。

とても効果的な新商品を売り出したとしても、宣伝方法によっては大ヒットにも成り得ますし、逆に、全く売れないこともあります。

ソフトウェア開発においてはどうでしょう。
開発時に作成するドキュメントを例にあげます。

ドキュメントはソフトウェア開発には必ず必要な成果物の1つです。
設計書や操作マニュアルなど、さまざまなドキュメントを作成していきます。(アジャイルはドキュメントを書かない事はありません)

これらのドキュメントは、見る人が理解しやすいことが一番の目的ですので、開発者が必要と思う事柄を事細かくたくさんの文章で書いても、(漏れなく文書に残すことはできますが)読むだけで大変になり、理解する、または、ほしい情報を見つけるには多くの時間が必要となります。

 

 理解しやすいドキュメントを書くための3つのヒント

では、どのように書くと理解しやすいドキュメントが書けるのでしょうか。
以下にいくつかのヒントを挙げます。

ヒント1:構成は全体から詳細

まずは全体が把握できる概要を記載したうえで、詳細な説明を続けて記載します

ヒント2:A3用紙1枚で表現

可能であればA3用紙1枚で伝えたいことを表現します
(A4用紙2枚の見開きでも構いません)

ヒント3:文章よりも図で表現

文章を極力減らし、図や表で(吹き出しなどを付けて)表現します

 

 ドキュメント作成で一番大切なこと

他には、一番伝えたいことを大きな字で表現するなどのテクニックもありますね。

一番大切なことは

読む人がいかに短時間で理解できるか

を意識して作成することです。
※そういった意味では、マインドマップは良いツールです

ここでは開発時のドキュメントを例に挙げましたが、他に、プレゼン資料、ポスター、広告、など、さまざまな場面において上記のヒントが使えます。

ちょっとした意識で大きな効果が得られるかもしれません。
是非、試してみてください。

 

なお、弊社の受託開発メンバーによる、「わかりやすいドキュメントを書くコツ」のシリーズ記事を連載していますので、以下より合わせてご覧ください。

参考
わかりやすいドキュメントを書くコツ(1):読み手をイメージする
 はじめに弊社のサイトを訪問して下さる方の多くはSE(システムエンジニア)やプログラマーの方ではないかと思いますが、皆さんの中にはコードを書くのは得意だけ...

Follow me!

この記事を書いた人

阿部智紀
阿部智紀
トラスティア株式会社 専務取締役
テクニカルディレクター
長期に渡り、アジャイル開発を推進・実行しています。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です