システム開発におけるテクニカルライティングの大切さ

われわれ日本人の多くは、日本語という言語で意思疎通をおこなっています。もちろん、この記事も日本語でかかれています。
しかし、日本語は曖昧な表現や異口同音、文脈によって意味の変わる単語も多く、相手に伝わらないことも多々あります。
それは、要件定義や設計といったシステム開発においても同様です。
そこで今回は、相手に伝わる日本語の書き方、テクニカルライティングについて学んでいきましょう。

テクニカルライティングとは

みなさんはテクニカルライティングという言葉をご存知でしょうか。
テクニカルライティングとは技術的内容を目的や読み手に合わせて分かりやすく伝える手法です。
つまり、技術文章の多くはテクニカルライティングといっても過言ではないでしょう。

テクニカルライティングをうまく利用することで、相手に伝わりやすくなり、
コミュニケーションによるズレを減らし生産性の向上が見込めます。

システム開発案件「おにぎりプロジェクト」

たとえば、「おにぎり」を想像してください。みなさんはどういうおにぎりを想像しますか？具は？海苔は？暖かい？冷たい？

いろいろありますよね。これをシステム開発に当てはめてみましょう。

要件定義フェーズ

顧客「おにぎりが食べたい！」

エンジニア「はい、おにぎりですね？どんなのですか？」

顧客「シャケがいいかな。海苔もまいてね」

エンジニアは要件定義書に次のように書きました。

• 海苔を巻いたシャケおにぎり

設計フェーズ

エンジニア「よーし設計をするぞー。要件定義書を見よう。ふむふむ海苔をまいたシャケおにぎりか・・・よーし」

エンジニアは設計書に次のように書きました

• 市販の海苔を全面に巻いた三角のシャケおにぎり。大きさはこぶし大にする。

設計フェーズ

エンジニア「よーしおにぎりを作ろう。そのために設計書を見よう。こぶし大のシャケおにぎりで海苔を前面に巻いているんだね。僕のこぶしは小さいからな。。。よーし」

エンジニアは次のようなおにぎりを作りました。

• 「日本の市販の１枚の海苔を全面に巻いた三角のシャケ」おにぎり。おにぎりの大きさはエンジニアのこぶし大（辺長３センチ）

検収フェーズ

エンジニア「できました！」

顧客「シャケおにぎりありがとう！とても小さい三角おにぎりですね・・・海苔が三角のシャケに巻かれていて味も思っているのと違う・・・あれ？」

どうやら顧客が本当に望んでいたおにぎりとは違うようです。

おにぎりプロジェクトを振り返る

このおにぎりプロジェクトは失敗してしまいました。これはなぜでしょうか。

システム開発ではフェーズが下流に向かうにつれて抽象的なものから具体的なものに変化します。
この抽象⇒具体という流れにはギャップが存在します。それが、今回の場合プロジェクト失敗につながったのです。

では、このギャップをどう埋めていけばいいのでしょうか。
その一つにテクニカルライティングを適用することで埋められることができます。

システム開発案件「おにぎりプロジェクト」の続き

顧客「思っているシャケおにぎりとは違うから作り直してほしい」

エンジニア「わかりました。おにぎりは何が違いましたか？」

顧客「まず海苔は韓国のりにしてほしかったかな。おにぎりの形も俵型で、おにぎりの大きさは高さ15センチぐらいの大きなものがいい」

エンジニア「うーん・・・設計からやり直しますね」

設計フェーズ

エンジニア「そうだ、テクニカルライティングを適応しよう。表で仕様を示そう。」

おにぎりの仕様は以下のとおりとする。

具：シャケ
海苔：韓国のり
形：俵型
大きさ：横に置いたときの高さを15センチ

エンジニア「しかし、次の項目がわからないな・・・」

米の種類：？？？
全体の重さ：？？？
具の大きさ：？？？。。。。（などなど

そこでエンジニアは顧客に聞きにいきました。すると顧客はすべて埋めて返答してくれました。

検収フェーズ

エンジニア「今度こそできました！」

顧客「おお、ありがとう。もうおなかペコペコ～。おにぎりの仕様はどれどれ・・・」

（表の横におにぎりの図）

顧客「仕様書を見ればひとめでわかる！うん！これをもらおうかな！ありがとう」

こうしておにぎりは納品されました。

おにぎりプロジェクトのまとめ

おにぎりプロジェクトの差し戻し後の設計書では次のことが反映されていました。

• 図表を利用している
• 一文一意
• 主語の明確化
• 数値の利用

反映したこれらはすべてテクニカルライティングのテクニックです。

では、順に説明していきます。

まず、図表を利用していることで、パッと目につきます。それにより重要なことであるとわかります。
さらに、文章量をへらすことができるので、簡潔に伝えることができます。

次に、一文一意です。これは一つの文章にひとつの意味をもたせるということです。
これにより、主語と述語が1対１の関係にあるので、わかりやすくなります。

さらに、主語の明確化。対象となるものを明らかにすることで、読み違いを防ぎます。例えば

• 市販の海苔を全面に巻いた三角のシャケおにぎり。大きさはこぶし大にする。

という一文ですが、「なにの」大きさなのかがわかりません。また、おにぎりについてもどこまで修飾されているかがわかりません。そこで主語を明確に記述してみましょう。

• 市販の海苔を全面に巻いた、三角形のシャケおにぎり。おにぎりの大きさはこぶし大にする。

これだけでもずいぶんとかわりますね。

そして、数値の利用です。曖昧な表現を明確にできるので、読み手の認識違いを防ぐことができます。
ここではこぶし大が、自分のこぶしなのか、子供のこぶしなのか、大人のこぶしなのかで変わるため、客観的にわかる数値に変えましょう。

おわりに

今回はテクニカルライティングの大切さをお伝えしました。おにぎりプロジェクトのように書き方ひとつで生産性が大きく変わることをおわかりいただけたでしょうか。
また、伝わりやすい文章は、読み手もストレスが少なく読むことができると思います。今回の例ではほんの一例を取り上げさせていただきました。
しかし、実際は、こそあど言葉を減らすことや接続語を正しく使う、といったことなど、論理的な文章作成能力が多々問われます。
日本語という言語を習得することはプログラミング言語を習得することよりも難しいですが、みなさんもぜひさまざまなテクニックを習得してください。

ウィズテクノロジーで一緒に働きませんか？
分野を限定せず幅広い事業を展開。新しい技術の導入にも積極的に取り組んでおり、チャレンジや成長する機会が沢山。
あなたの経験・知識を活かしながら一緒にIT業界を盛り上げて行きましょう！
採用情報詳細はコチラ