【講義】エンジニアが学ぶべき、わかりやすい文の書き方【開発ドキュメント】

はじめに
分かりやすさがなぜ必要か
分かりやすい文とは
1. 例：わかりにくい文
2. 例：校正した文＋簡易な説明
最後に
おすすめ参考書

はじめに

本講義はソフトウェア開発をチームで行ったことがない、これからチームで開発を行う予定がある人を対象としています。

また、開発ドキュメントの講義では「ルールとしてこういったものがあるよ」という紹介しかできません。

具体的な例やより詳細な知識を手に入れたいと思った場合には、他サイトや最後に示す参考書などを参照してみてください！

さて、一般的にチーム以上の単位でソフトウェア開発等を行う際、要件定義書や外部設計書、内部設計書など様々な開発ドキュメントを作成することになります。

開発ドキュメントはなぜ作成するの？という疑問にはいつか詳しく説明する予定なので、今は開発ドキュメントを作成することで結果として嬉しいことがたくさんあるとだけ伝えておきます。

開発ドキュメントを書くために、まずは「わかりやすい文を書ける」というところから勉強しましょう！

分かりやすさがなぜ必要か

「チャイムから〇〇分かかりました」って言葉聞いたことありますか？

そのあとに続くのは「30人で合計××分も時間を無駄にしました」みたいな感じですよね。

子供の頃は「えー○○分しか無駄になってないしー」と納得しかねましたよね。というか、今でもあのいい分には疑問です。

同じタイミングの○○分を皆で同時に無駄にしているのに、それを加算するのは些かおかしいのではないかと。

しかし、開発作業をする場合にはこれが馬鹿にできません。無駄にする時間が同じタイミングではなく、開発期間に影響する可能性があるからです。

わかりにくい文を作成したことで「これはどういう意味でしょうか？」という問い合わせメールが読み手全員から送られてくるとして、その対応にかかる時間が1人3分だとしましょう。

読み手が20人いれば自分の時間が60分。読み手20人の合計時間が60分。合計で2時間も遅れます。これがたくさん積み重なるとどんどん納期は遅れていきます。

さらに、わかりにくい文により情報が誤って伝わった場合、開発は取り返しのつかないことになってしまいます。

これでは困ってしまうので、わかりやすい文を書きましょう。ただそれだけのことです。

分かりやすい文とは

では、わかりやすい文とはどういった文でしょうか。

読み手はドキュメントに書かれた文を基に何かしらの行動を起こします。

つまり、次のように文が作成されているとわかりやすい文だといえます。

読み手に情報を正確に伝えることができる
読み手に情報の内容を確実に理解させることができる

このため、わかりやすい文には次のような要素が必要となります。

正しい日本語文法
読みやすく、明確で、簡潔な表現方法

説明自体は以上ですが、これでは何もわからないと思います。

なので、わかりにくい文と、それを校正した文＋簡易な説明を載せておきます。

例：わかりにくい文

鮭は下流より上流に進み、この辺りへ到達します。
確認した後、クリックを行います。
ダウンロードすることができます。
「ファイル」を選択すると、「オプション」を開きます。
けーとらさんのモチベーションが、お金が関係することで上がります。
狭い従業員用の道を歩く。
台風の進路が変わったため、出社における影響はない。
各人物ごとの運動量。
新技術Xにより目標を達成できる。Xは○○によって作成されました。
スイッチAはスイッチBのように動作しない。
XとYの1/2の合計をZに記入してください。
合計で5～60人が出席する。

例：校正した文＋簡易な説明

鮭は下流から上流へ進み、この辺りに到達します。
- 始点に対しては「から」、終点に対しては「に」。
確認した後、クリックします。
- 「名詞」＋「する」で動詞になるものに、「行う」等を付けない。
ダウンロードできます。
- 「名詞」＋「する」（動詞化）＋「こと」（名詞化）と名詞を名詞に戻さない。
「ファイル」を選択すると、「オプション」が開かれます。
- ファイルは読み手が選択する。オプションはその結果開かれる（受け身）。
お金が関係することで、けーとらさんのモチベーションが上がります。
- 主語と述語を近づける。
従業員用の狭い道を歩く。
- 修飾語と被修飾語の係り受けを適切にする。
台風の進路が変わったため、出社に影響はない。
- 不要な語句（無くても意味が変わらない語句）は省く。
各人物の運動量。/人物ごとの運動量
- 「各」と「ごと」のような同じ意味の言葉を二重で使わない
新技術Xにより目標を達成できる。Xは○○によって作成された。
- 統一感のある文末にする。
  例：「できる/された」「できます/されました」
スイッチAはスイッチBの動作と異なる。
- 「のように」の後で否定しない。
  例：「スイッチBと同じく動作しない」「スイッチBと異なる動作をする」
Xと、Yの1/2の合計をZに記入してください。
- 句点を的確に利用する。
  例：「Xと、Yの1/2の合計」「Xの1/2とYの1/2の合計」
合計で50人～60人が出席する。
- ～で数の範囲を示す際は注意する。誤って伝わる可能性がある場合、両方に単位を付ける。
  例：「5人～60人」「50人～60人」「50～60人」

最後に

いかがでしょう。もちろんこの記事を読んだだけでは、能力が向上することはありません。

しかし、これをきっかけとして意識的に文章を書いていくことで、今後のチーム開発で何かしら開発ドキュメントを作成することになったとき、役に立つことは間違いありません。

日経でもエンジニアの文章力について特集が組まれていることからも、このわかりやすい文を書く能力が必要とされていることが分かると思います。

ちなみに、開発ドキュメントは小説ではないので表現技法（テクニック）は必要ありません。変な言い回しを覚えてもそれは小説家になろうでしか生かせないのでご注意を。