Posted on

ITエンジニアにドキュメント力がとても大切な理由

「認識齟齬です」この言い訳のような便利な言葉は、システム開発において禁句です。
問題の原因として、この言葉が使われていた場合、そのプロジェクトは危険だと考えた方が良いでしょう。本来であれば、なぜ認識齟齬が起きたのかが重要なのに、そこを追求せずに、この便利な言葉で片づけてしまっていたら、今後も認識齟齬による問題は頻発することになります。
ところで、システム開発プロジェクトでは、数多くのドキュメントを作ることになりますが、ITエンジニアの中にはドキュメント作成を苦手とする人や面倒に感じる人もいるでしょう。しかし、ドキュメントは、プロジェクトの成否を左右する重要な要素です。SaaSやパッケージ製品全盛の今どき、そもそも設計書は必要か?という疑問もあるかもしれませんが、ITエンジニアにとって分かりやすいドキュメントを作成するスキルは、ドキュメント作成に限らずエンジニアの基本的な能力を向上するためにとても大切だと考えています。
今回の記事では、なぜITエンジニアにドキュメント力が大切か、どのようにドキュメント力を上げたら良いかについて紹介します。

かんたんイラスト(記事を読む時間のない人へ)

なぜ認識齟齬が生まれるのか

認識齟齬という言葉は、文字通り複数の人の間で認識が異なったということ、つまり、人によって理解した内容が違っているということです。その理解がどこからくるかというと、お互いの会話、あるいは話のネタとして使ったドキュメントです。システム開発の仕事では、この認識齟齬を防ぐために、議事録をとってお互いの発言や合意事項の理解を合わせることもしますが、それでも齟齬が発生するのは、なぜでしょうか。
その原因は2つあります。
1.説明がわかりにくい
2.ドキュメントが分かりにくい
説明が分かりにくいことも原因ですが、ドキュメントには、説明資料だけでなく最後の砦となる議事録も含むと考えると、ドキュメントが分かりにくい方が問題は大きいです。

ドキュメントの重要性

前述のとおり、認識齟齬の原因の一つはわかりにくいドキュメントにあります。システム開発で作成するドキュメントは、要件定義書、基本設計書、テスト仕様書、進捗報告書、議事録など多岐にわたり、多くの工数が必要となるため、必要性に関して疑問視するITエンジニアもいるでしょう。
しかし、数多くのシステム開発プロジェクトを見てきて感じることの一つに、「ドキュメントが分かりにくいプロジェクトは失敗する」という経験則があります。それを裏付ける構造は下記のように説明できます。
ドキュメントが分かりにくい
  ↓
認識齟齬を生む
  ↓
障害や手戻りが発生
  ↓
遅延する(ひどいと炎上する)

システム開発プロジェクトは、クライアントも含めたチームで協力して進めていく仕事であり、メンバー間のやりとりやクライアントとの合意形成はドキュメントをベースに行います。分かりにくいドキュメントがあると、メンバー間やクライアントと認識齟齬が生まれます。さらに理解が異なったままで開発を進めると後工程で障害として発見され、手戻りあるいは進捗遅延が発生し、最悪の場合、炎上プロジェクトとなってしまいます。「ドキュメントの分かりやすさ」はプロジェクトの成否を端的に予測できる要素と言えるのです。
SaaSやパッケージ製品の導入では、ドキュメントではなく実際のシステムを見ながら仕上げていくというアプローチをとることもありますが、指摘はドキュメントに記録して管理することになりますので、ドキュメントが全くないということはありません。iPhoneが世に出た時には、取扱説明書がなくて驚きましたが、そのうち機能を紹介するwebサイトが登場して、そのサイトを見て理解していくようになってきました。ただ、その解説ページが難解なために、機種変更の際にLINEのトークが消失したとかmusicが消えてしまったなどの問題が起こっています。この時代においても、いまだに分かりやすいドキュメントは、問題を発生させないために必要なものなのです。

技術力と説明力、どっちがチームリーダーに必要か?

さて、チームリーダーを任命する場合、「技術力は高いけど説明が下手な人」と「技術力は高くないけど説明が上手な人」のどちらを選びますか?
私なら、2つの理由から後者を選びます。
理由の1つ目は、チームリーダーはメンバーに対して指示を出しますが、もしも分かりにくい指示によって間違った方向で開発が進められてしまったら、その手戻りは進捗遅延の原因となります。それが大量生産の指示であった場合には、恐ろしくて想像したくもありません。
2つ目は、プロジェクトの重要な会議における効率です。ステコミやマネジメントへの進捗報告会は、時間単価の高い人達の集まりです。その報告会で説明が分かりにくいと、全員の理解に時間がかかり会議で無用な時間を使ってしまうことになります。時間切れとなり、あやふやなままで進むことも危険ですし、別途説明する時間を調整するのも非効率です。
チームリーダーには、ミスを未然に防ぐためと効率性の観点から説明する能力がとても重要なのです。
なぜ、ここで説明の重要性を伝えたかというと、これまで500人以上のエンジニアと一緒に仕事をしてきた経験から、説明上手な人は、ドキュメント力も長けているのです。逆もまた然り、ドキュメント力が高くなると説明も上手になるため、ITエンジニアはドキュメント力を鍛えることで、基礎的なスキルが向上しポジションを上げていく道が開けるのです。

ドキュメント力を上げるためのヒント5つ

ドキュメントがわかりにくいのは、情報を整理できていないことが最大の要因です。分かりやすいドキュメントを作成することは、情報を整理することと同じで、情報が整理されることでドキュメント力は上がります。では、どのようにすれば情報を整理することが出来るようになるのでしょうか。ドキュメント作成に役立つ情報整理のヒントを紹介します。


1.分解する:物事を構造的に捉える
ITエンジニアは、物事を構造的に捉える能力が必要です。構造的とは、全体を把握した上で構成要素に分解していくことです。
例えば、システム機能一覧を作る時に、画面、IF、バッチ、帳票などに機能を分類することも構造的な捉え方の一つです。それが出来ると「今回作るシステムは、全部で99機能あり、その内訳は、画面とIFと5つの機能に分類され、画面が10機能で、IFが何機能で...」と上手に説明できるようにもなります。この構造的な考え方は、システム開発において、テストケースの抽出や障害の原因特定など様々な場面で必要となるため、「全体で何個、何種類に分類でき、分類毎の内訳はこう」という思考で常に考えることが大切です。


2.捨てる:情報に重要度を付ける
情報整理が得意ではない人は、情報量に溺れています。整理することは、つまり重要度を付けるということで、極端に言うと、重要ではない情報は捨てるということです。具体的な訓練の方法としては、ドキュメントを作成する際に、まずは最も重要な情報だけで作ってみる、そこで伝えたいことが十分でないと感じるようなら、次に重要な情報を付加した版を考えてみる。このようにドキュメントに載せる情報を重要度によって限定して、重要度によるバージョンをいくつか作っていくこともドキュメント力が向上するやり方の一つです。最初からすべての情報を盛り込もうとするから混乱し、情報過多でわかりにくい内容になってしまうのです。まずは情報に重要度を付けることから始めましょう。

3.視点を変える:相手の立場になる
システム開発で作成するドキュメントは、種類によって見る相手が異なります。見る人がクライアントかプロジェクトメンバーか、知識を持っているか持っていないか、何を知りたいと思ってるか、どのように活用するかなどを考え、見る相手とその目的で情報を整理します。相手や目的で絞り込んだ情報だけを使ってドキュメントを作成することで、分かりやすさが格段に上がります。


4.訓練する:アウトプットを習慣化する
テクニックもありますが、やはり訓練も必要です。ITエンジニアは、学習意欲の高い人が多く、知識をインプットしていることが多いと思いますが、アウトプットが疎かになっている可能性もあります。例えば、テレビでインタビューをするシーンがあれば、自分がゲストだったらと想像して何と答えるか、自分がホストならどういう質問をするか、本を読んだら一言で伝わる感想を考えるなど日頃から自分の考えを伝える訓練をすることで、情報の整理力が向上するでしょう。インとアウトの両方をバランスよく訓練することがスキルアップに繋がります。
5.ツールを使う:情報整理アプリやメモ帳を活用する

情報整理が上手ではない人は、考え過ぎている可能性もあります。綺麗に正規化しようとして、結果として混乱してしまう。後から見直すことを前提にいったん仮で分類するという整理の仕方でも良いのです。私は、あるメモ帳アプリを使ってますが、どのカテゴリに登録するか迷った時は、そのメモにキーワードをtag登録し、名無しのカテゴリに入れてしまいます。tagを入れる際に、これまで入れたtagの候補が出ますし、後からtagで一覧化することもできるので、情報を再整理する時に便利です。ツールを活用することも情報整理力の向上に効果的です。

まとめ

わかりやすいドキュメントは、ミスコミュニケーションを無くし、手戻りリスクを減らすことになるため、エンジニアとしての評価が高まります。エンジニア自身にとっても、認識齟齬による手戻りなど無駄な労働が減ることにも繋がります。ドキュメント力を上げるためには情報の整理が必要ですが、それは考え方や訓練によって鍛えることが可能です。今回紹介した5つのヒントが、ITエンジニアのパフォーマンスアップに役立てたら嬉しいです。

出典:柴田秀夫@ARAKADO※転載は筆者承諾済