システム開発の基本設計書、要件定義書、テスト仕様書、取扱説明書やマニュアル…。「プログラミングは苦にしないけど、ドキュメント作成は気が重い」というシステムエンジニアも少なくないようです。
「正しく動くシステムを作るよりも、人間に正しく理解させる方が100倍難しい」といわれると、共感してしまいますが、来週までに作らなければいけない資料があるという現実は変わりません。どうせ避けて通れないなら、いっそ苦手意識を克服して、システムエンジニアとしての「強み」に変えてしまいたいところです。
今回は、プロジェクトをうまく進めたいシステムエンジニアに向けて、ドキュメンテーションを作成するうえで押さえておきたいポイントを紹介します。
ドキュメンテーションスキルを向上させるメリット
ドキュメントを介した効率的な情報伝達は「ドキュメント・コミュニケーション」とも呼ばれ、生産性を左右する重要なスキルのひとつです。
適切かつスピーディーに内容を理解できる「わかりやすいドキュメント」は、一度作ってしまえばコミュニケーションの時間を大幅に短縮できます。とくに作成者は、口頭で繰り返し説明する手間をドキュメントが引き受けてくれるため、より重要な業務に時間と労力を投入できるでしょう。
メンバー間のノウハウや知見・ベストプラクティスなどをスムーズに共有できるのもメリットのひとつです。プロジェクトに携わるメンバー全員のドキュメンテーションスキルが高まれば、チーム全体のパフォーマンス向上にもつながります。
テレワークが当たり前になりつつあり、対面でコミュニケーションを取る機会が減っている昨今、ドキュメンテーションの重要度は今まで以上に高まっているといえます。
テレワークでは、新入社員が先輩社員の仕事ぶりを見て学べないため、業務遂行に必要な情報を入手するのが難しくなっているケースが増えているといいます。そのため、必要な情報がわかりやすく整理されたドキュメントの作成スキルは、人材育成の観点からも重宝されるでしょう。
さらに、コツをつかんで効率的に作成できるようになれば、憂鬱なドキュメンテーションの時間短縮にもつながるので、まさに「良いことづくめ」です。
ドキュメント・コミュニケーションにおける3つの重要ポイント
「ドキュメント・コミュニケーション」は、2008年に元マッキンゼーの中川邦夫氏によって提唱された概念です。その基本原則は次の3つです。
- 解・動・早
- 問題解決コミュニケーション
- スタンド・アローン
「解・動・早」は、読者に「わかっていただく」「動いていただく」「できるだけ早いアクションを取っていただく」というドキュメントの目的を示しています。ポイントは単に理解を促すだけでなく、ドキュメントを読んだあとに取るべき「具体的なアクション」を提示するという点にあります。
次の「問題解決コミュニケーション」は、ドキュメントのゴールを「読者の問題解決」として捉えるコミュニケーションの型です。問題解決の方法を提示するという目的意識を持つことで、ドキュメントの構成が明確になり、スムーズな情報伝達が可能になります。
最後の「スタンド・アローン」は、作成者から補足の説明がなくても、ドキュメントだけで情報伝達が完結する状態。これによりコミュニケーションの効率化が図れるでしょう。
この「理想的なドキュメント・コミュニケーション」を実現するには、事務処理能力や論理的思考力・問題解決力・コミュニケーション能力などの総合的なポータブルスキルが要求されます。
複雑かつ膨大な情報をわかりやすく分類するためには、情報整理能力も欠かせません。ありのままの情報をドキュメントに詰め込んでしまうと、似たような内容が何度も出てきたり、論点がつかみにくかったりと煩雑な資料になってしまいます。
ただし前提知識や重要なポイントまで削ってしまうと、やはり伝わりにくい資料になります。漏れや重複がない「MECE（ミーシー/ミッシー）」の状態を実現するためのロジカルシンキングや、必要最低限のポイントを簡潔に抽出する要約力が、ドキュメンテーションの肝といえるでしょう。
ドキュメンテ―ション作成で求められるスキル
誰が読んでもわかりやすい資料にするためには、語彙や文章力・図解力も不可欠になります。当然のことながら、PowerPointなど資料作成に活用するツールの操作スキルや、デザインスキルも重要です。
現場によっては、英語でのドキュメント作成が求められるケースもあります。たとえば外国籍のメンバーが所属しているチームや、海外のクライアントをターゲットにしているプロジェクトに参加するケースです。
その場合は、外国語での文章作成スキルが必須で、海外の文化やビジネスにおける慣習、法律などの知識も必要です。
これらのスキルを高めていくことで、効率的に精度の高いドキュメントが作成できるでしょう。
とはいえ上記のスキルを身につけるのには手間と時間がかかるもの。「もっと即効性の高いドキュメンテーションの攻略法が知りたい」という人のために、ここからはより具体的な「ドキュメントのまとめ方」を解説していきます。
「誰に何を伝えるのか」を明確にする
今回は、ソルクシーズの社員に「ドキュメントを仕上げる際に心がけていること」をヒアリングしてみました。さまざまな声のなかから、ドキュメント・コミュニケーションに必要なスキルをピックアップしたうえで、効果的なまとめ方をレポートしていきます。
まず欠かせないのが、ドキュメントの適切な作成方法を理解すること。ドキュメンテーションには効果的な手順や型があり、それに沿って作成できるようになるのが上達への近道です。
ドキュメンテーションに着手するときは、最初にターゲットと目的を設定します。
先述したように、ドキュメントは何らかの課題を解決するために活用するものです。そのため「誰に向けて作成するのか」「読み手はどのような課題を抱えているのか」を明確にしないと、適切な情報伝達は困難になります。
ソルクシーズ社員へのヒアリングでも、意見をくれた7人全員がエンジニアにとって大事なこととして、「誰に何をしてもらうためのドキュメントなのかを明確にすること」を挙げています。目的が明確になれば、ドキュメントの構成にムダがなくなり、ターゲットにとってわかりやすい言葉や表現を選ぶことができます。
ソルクシーズ社員が語る大事なポイント①
「わかりやすく、簡潔に。何をすればいいのか、どういう結果が出ればいいのか、必要なことだけ記載しています。他のドキュメントとの関連についても添えておいたほうがいいですね」
ターゲットと目的が決まったら、さっそくドキュメントを作成…いや、その前に、設計図を作りましょう。ドキュメントをいきなり冒頭から作成していくと、手戻りが発生してしまい非効率です。漏れや重複が発生する可能性も高まるため、あらかじめ全体像を把握しておくことが重要になります。
ドキュメントの目次をつくるイメージで、書くべき内容を箇条書きしていきます。そのうえで、内容が伝わりやすいように適切な分類・並び替えをしましょう。
ストーリーと全体の流れを整理する
伝わりやすいドキュメントの設計図を考えるうえで重要なのは「ストーリー」と「流れ」です。
「ストーリー」とは、読み手が問題を認識して解決するまでのプロセスのこと。たとえば冒頭で何についてのドキュメントなのかという「概要」や、作成の「背景」、具体的な「課題」などを共有したうえで、本編にて「対策」を紹介していくというのが、よく使われるストーリーです。
大まかなストーリーが決まったら、次は詳細な情報をどのような順番で配置していくかという「流れ」を考えます。ここでもいくつかのコツを押さえることで、スムーズに読み手の理解を促す資料が作れるでしょう。
ポイントの一つは「全体から詳細へ」という順に構成すること。ドキュメントの冒頭を「概要」ではじめたように、各パートでも新しい話題に移るときは事前に「これから何について語るのか」を提示します。
先に要点を伝えることで、読み手が現在地を把握でき、不要な混乱を防げます。作成者にとっても情報の取捨選択の基準が明確になるため、簡潔な資料になりやすいでしょう。パートごとの見出しでも、要点が理解しやすい言葉選びが大切です。
趣旨を明確にするという意味では、「結論から述べる」のも効果的です。
伝わりにくい資料にありがちなのが、手順や見解を述べるときに「なぜそうなるのか」「根拠は何なのか」といった補足情報から書きはじめてしまうこと。これだと、読み手は何の話をしているのかわからないまま文章を読み進めなければなりません。重要な情報も埋もれやすくなるでしょう。
「結論を述べた後に、その理由とデータなどの根拠を伝える」という流れを意識すると論点がはっきりします。重要なポイントをわかりやすくするため、最後にもう一度結論や要点の振り返りをするというのもおすすめのテクニックです。
手順や出来事などを伝えるときは、時系列に沿って並べることも大切。加えて「説明のパートと参考データのパートを分けて、言いたいことがシンプルに伝わるようにする」「基本的な説明の後、応用編やハイレベルな内容に言及する」といった流れも意識したほうがいいでしょう。
なお、読み手は必ずしもドキュメントを頭から順番に読んでいくとは限りません。目次を確認して必要なところだけを拾い読みするというシチュエーションもあるため、「前のページに戻って確認しなければならない構成にしない」といった工夫をするとより親切です。
「誰が読んでもわかる」を実現するための工夫
ドキュメントの設計図を組み立てたら、ようやく資料の内容にあたる文章や図・表・グラフなどの作成に取り掛かります。
資料を作るときは「誰が読んでもわかるように記載すること」がポイント。つねに「ドキュメントにはそれを読む人がいる」ということを意識して、不明瞭な部分を残さないように注意を払う必要があります。あるソルクシーズ社員が心がけていることを、いくつか紹介しましょう。
ソルクシーズ社員が語る大事なポイント②
「テストの仕様書の内容が曖昧だったばかりに、テストをやり直したことがあります。誰が読んでも同じように理解してもらうために、『長文を避け、簡潔に書く』『箇条書きの粒度を揃える』『客観的に記述する』といったことを意識しています」
ソルクシーズ社員が語る大事なポイント③
「手順書は、誰が作業しても同じプロセスになるのが基本です。作業をアクションごとに分割し、必要があればスクリーンショット等を使って、曖昧さを排除しています」
文章はできるだけ文字数を少なくしたほうが、読み手に伝わりやすくなります。情報量が多い場合でも「一文を短く区切る」「ページを分ける」など、一度に伝えるメッセージをコンパクトにすることが大切です。ちなみにパワーポイントなどであれば「ひとつのスライドに盛り込む話はひとつまで」が基本です。
しかし、情報量を減らしすぎて伝わらなくなってしまうのでは元も子もありません。情報の過不足を判断するときは、資料のターゲットが知っていること・知らないことを意識して、「専門用語の解説や言い換えが必要か」「背景や前提情報を説明すべきか」を考えましょう。
また、図・表・グラフの効果的な挿入も読み手の理解を助けます。とくに数値やものごとの仕組み・構造を提示するときは文章だけだとイメージがしにくいため、ビジュアルでの表現がおすすめです。グラフは伝えたい情報に合わせて、適切な種類のものを選択しましょう。
細かいところですが、資料のフォーマットや文字のサイズ、フォント、カラーイメージなども一貫したルールで統一すると、見やすい資料になります。色はあまり多すぎるとノイズになるのでメインのカラーをひとつ決めて、そのほかは最大でも2〜3色程度に抑えましょう。
文章でも、使用する単語は統一して、ひとつのことを示すのに複数の単語を用いないようにするとわかりやすくなります。主語が曖昧になるのを避けるために、「あの、その、この などの指示代名詞を極力使わない」ことも大切です。
客観的な記述をするうえで効果的なのは、第三者に資料をチェックしてもらうことです。繰り返しフィードバックを得るなかで、徐々に誰かの目を通さなくても自分が作成した資料を客観的に見る目が養われます。
いかがでしょうか。なかなか奥が深いドキュメンテーションの世界ですが、ここに書かれていることを徹底するだけでも、読み手にとってわかりやすい資料を作れるようになるはずです。
それではみなさん、締め切りまでに資料提出をよろしくお願いいたします。
※この記事は2020年7月14日に公開した記事を再編集しています。
