システム開発の基本設計書、要件定義書、テスト仕様書…。プログラミングは苦にしないけど、ドキュメント作成は気が重いというシステムエンジニアは少なくないようです。
「正しく動くシステムを作るよりも、人間に正しく理解させる方が100倍難しい」といわれると、つい同意したくなっちゃいますが、来週までに作らなければいけない資料があるという現実は変わりません。
テレワークが当たり前になりつつある昨今、ドキュメンテーションの重要度は今まで以上に高まっています。
今回は、ソルクシーズの社員に「ドキュメントを仕上げる際に心がけていること」をヒアリング。苦手意識があるエンジニアのみなさんの参考になればと考える次第であります。
7人のエンジニアが声を揃えるのは、「誰に何をしてもらうためのドキュメントなのかを明確にすること」「誰が読んでもわかるように記載すること」です。
目的が明確になれば、ドキュメントの構成にムダがなくなり、ターゲットにとってわかりやすい言葉や表現を選ぶことができます。ソルクシーズ社員が心がけていることを、いくつか紹介しましょう。
「テスト仕様書の内容が曖昧だったばかりに、テストをやり直したことがあります。誰が読んでも同じように理解してもらうために、『長文を避け、簡潔に書く』『箇条書きの粒度を揃える』『客観的に記述する』といったことを意識しています」
「わかりやすく、簡潔に。何をすればいいのか、どういう結果が出ればいいのか、必要なことだけ記載しています。他のドキュメントとの関連についても添えておいたほうがいいですね」
「手順書は、誰が作業しても同じプロセスになるのが基本です。作業をアクションごとに分割し、必要があればスクリーンショット等を使って、曖昧さを排除しています」
内容のわかりやすさと同様に、重要なのは「ストーリー・流れ」です。
資料には目次を付け、「全体から詳細へ」という順に構成すること。読み手の理解を促進するために「手順に沿って」「過去～現在～未来」「基本的な説明の後、応用編やハイレベルな内容に言及する」といった流れも意識したほうがいいでしょう。
パワーポイントなどで作成する説明書、設計書などにおいては、「ひとつのスライドに複数の話を盛り込まない」「あの、そのなどの指示代名詞を極力使わない」「使用する単語は統一し、ひとつのことを示すのに複数の単語を用いないようにする」ことにも気をつけたいですね。
構成面では「前のページに戻って確認しなければならない構成にしない」「説明のパートと参考データのパートを分けて、いいたいことがシンプルに伝わるようにする」といった工夫も効果的です。
いかがでしょうか。なかなか奥が深いドキュメンテーションの世界ですが、ここに書かれていることを徹底するだけでも、読み手にとってわかりやすい資料を作れるようになるはずです。
それではみなさん、締め切りまでに資料提出をよろしくお願いいたします。
