はじめに

設計書というのは往々にしてメンテナンスされないものです。そもそも設計書というドキュメントは必要なのか？という議論もよく見かけます。設計書の要否に関しては、人それぞれ考えはあると思いますが、(どちらが良いかは置いておいて)ここでは設計書は「必要」という前提で、ではどうすれば設計書をメンテナンスする文化を醸成するかを考えてみます。

設計書の存在意義をメンバーに共感してもらう

設計書の存在意義を本当に理解しているメンバーは意外に少ないものです。「設計」というフェーズが存在するから書いている、お客様に納品するから書いている、リーダーに指示されたから書いている、なんてことも少なくありません。また、設計書の存在意義の解釈もメンバーによって違うことが多いです。このような状況で「設計書はしっかりメンテナンスしよう！」と言っても、メンバーのモチベーションを下げるだけです。そのため、

設計書の目的(なぜ設計書が必要なのか、設計書があることで何が幸せなのか)
設計書は誰のためのドキュメントなのか
設計書はどんな時に必要となってくるのか

をプロジェクト内(組織内)で定義して、メンバーに説明し共感してもらうことから始めます。

設計書のメンテナンス工数を確保する

設計書のメンテナンスが必要となるケースはいくつかあると思いますが、そのほとんどがプログラムの修正に伴うメンテナンスです。例えば、テスト時のバグ対応で処理フローを修正しそれにより設計書も修正が必要となった、なんてケースがその1つです。このケースの場合、テストのバグ対応をしながら残ったテストケースの消化もしなければならず、スケジュールに追われて設計書のメンテナンスまで手が回らずそのまま、、、なんてオチに繋がります。そのため、工数を見積もる時は設計書のメンテナンス工数も確保することで、メンテナンスまで手が回らない、、という事態を防ぎます。

メンテナンスしやすい設計書フォーマット・記載粒度にする

設計書の存在意義を共感してもらって、メンテナンス工数を確保しても、メンテナンスしやすい設計書フォーマット・記載粒度でないと、これはこれでメンバーのモチベーションを下げてしまいます。複雑すぎるフォーマット、細かすぎる記載粒度はなるべく避けたほうが良いと思います。

ソースレビューと同時に設計書も修正されているかを確認する

色々と述べてきましたが、そもそも設計書のメンテナンス作業を忘れては意味がありません。前項でも述べた通り、設計書のメンテナンスが必要となるケースのほとんどがプログラムの修正に伴うメンテナンスです。そのため、プログラムを修正してソースレビュー依頼が来たら、ソースだけでなく設計書も修正されているかを確認するフローにします。例えば、ソースレビュー観点に設計書も修正されているか、を盛り込む等です。ただ、重厚なフローにし過ぎるとかえって開発者が窮屈になってしまうので適度なやり方が良いと思います。

設計書の存在意義を定期的に振り返り確認し合う

定期的な振り返りや認識合わせは重要です。定期的に振り返りや認識合わせを行うことで、設計書をメンテナンスする文化を磨き上げていきます。

最後に

色々述べてきましたが、プロジェクトや組織の文化、メンバーの特性によるところも大きいと思います。そのため、本ページのやり方がベストというわけではなく、プロジェクトや組織の文化、メンバーの特性を考えながらそれにあった手法が良いと思います。本ページの手法はあくまで一例として捉えていただけたらと思います。

以上です。