組込み機器開発に限った話ではありませんが、開発時に作成する設計書等のドキュメントは関連メンバー全員の認識を統一するために重要なものです。もし認識にずれがあると、結合した際に全くシステムが動かないなんていう悲惨なことになります。あなたは過去に資料作った際に「この文章、何を言いたいの？」と指摘されたことはありませんか。本コラムでは、誰もが理解しやすいドキュメントを記載するために、私が実践している「目的と読者を意識すること」についてご紹介致します。
ドキュメントは関係者全員の意識統一をするための共通言語
昨今Linuxなどはソースコードを読みましょうといった流れになっていますが、あなたの周囲にも「プログラムが設計書」と言う方はいないでしょうか。確かに美しいプログラムコードは私などが感心してしまうぐらい読みやすく、理解しやすいものも多いかと思います。しかしながら、複数人数で開発を行うのが当たり前の開発プロジェクトにおいて、例えばテスターのようなプログラムコードを意識しない人に対して、プログラマーが上流設計をどのように解釈し、どのような手法で機能を実現しようとしているかということを意思表示するのは、美しいプログラムコードでは困難なのです。関係者全員の認識を統一させることができなかった結果、テスト項目に漏れが出て製品にバグが混入してしまうといった事故を引き起こしかねません。全ての仕様をきちんと理解していること、それをどのようなアルゴリズムで実現するかを文章で正しく表現し、関係者全員に統一した理解をもってもらうことは、組込み機器に限らず複数人での開発プロジェクトにおいては、重要なのです。
「ドキュメントの目的」と「読者を具体的に想像する」
上記で紹介したようなドキュメントを読んだ全員が同じ理解をできるようなドキュメントを作る際には、「ドキュメントの目的を設定する」、「読者を具体的に想像する」の２点が重要となります。
まずはドキュメントの目的について考えてみましょう。例えば、提案書なら「短時間にお客様があなたの提案を理解、判断いただく」でしょうし、テスト設計書なら「テスターが機能仕様を理解し、機能を網羅するために必要なテスト項目を洗い出す」ことになるかと思います。この目的はドキュメントを作るうえで絶対ブレてはなりません。
次に「読者を想像・意識する」点となります。たとえば一番わかりやすい例で言えば絵本などです。赤ちゃん向けの絵本に感じで文章をいくら並べても理解できません。赤ちゃん向けのドキュメントであれば、文字ではなく絵、しかも細かすぎる絵ではなく、大きなブロックで構成されるような絵で伝えることが重要になるかと思います。同様に小学校低学年向けの絵本であれば、ひらがなで大きな字で書くのが良いとわかるでしょう。読者の知識レベルを無視し、理解できない単語を使うことは、何も伝わらないという結果になり、目的は達成できません。ドキュメントを作る際には「ドキュメントの目的」をきちんと定義し、「読者を想像・意識する」ことに最大限に配慮しなければなりません。ちなみに当たり前のことではありますが、内容が間違っているといくら目的をブラさず読者を想像したとしても、間違った内容が読者に伝わることとなり、結果的にはバグの混入などの原因となりますので注意をしてください。
より良いドキュメントが、良い製品を生み出す
これまでお話したように、プロジェクトメンバー全員の意識を統一するためには、設計書などのドキュメントは有効な手段となります。しかしながら、そのドキュメントを記載する際に何も意識せず自分本位なドキュメントを作ってしまっては意味がありません。「ドキュメントの目的を設定すること」と「読者を想像・意識すること」の２点を意識して、読んだ人の誰もが統一した意識を持つことが出来るドキュメントを記載するのが重要となります。統一したドキュメントは、プロジェクトメンバー全員の意識統一を図ることができ、結果としてシステムや組込み機器の品質を向上、担保することにより良い製品を生み出すことにつながるのです。開発というとプログラムにウェイトをおきがちな人も多いかと思いますが、ドキュメントにも意識し、より良い製品を生み出していただければ幸いです。
個別相談も承っております。下記よりお申し込みください。
