Software Design 2024年10月号受託開発における設計ドキュメントの課題と解決案作成・管理のヒントを探るへの寄稿

はじめに

2024年9月18日に発売された、Software Design 2024年10月号の第1特集「再考設計ドキュメントの課題　二重管理しない，陳腐化させない」の「第1章：受託開発における設計ドキュメントの課題と解決案　作成・管理のヒントを探る」に寄稿させていただきました。

Software Design とは

技術評論社が出版している月刊の技術情報誌です。Webサービスを開発するソフトウェア業界のエンジニアにとっては説明不要と言っていいくらい鉄板です。

毎月様々なテーマについて特集を組んで取り扱っており、プログラミングだけでなく、OSやネットワークまで、その内容は多岐に渡ります。入門者・初心者向けの内容から実践的な内容も多く含まれているので、新人からベテランまであらゆるエンジニアにおすすめできる雑誌です。

定期購読をして、業界の最新情報をアップデートするのもおすすめです！

10月号の見どころ個人的推し

「再考設計ドキュメントの課題パート」は各社の経験談が豊富で読んでいて楽しい
- 2章中島さんのADR導入の事例の紹介。ただやってみただけではなく、プロダクションで実践導入されていた知見はとても参考になりました。ADRと設計ドキュメントの統合で、どちらもGit管理することに関心があります
- 5章の「OSS開発ドキュメント事情」は知らなかった世界なのでとても興味深かったです。あのコードコメントの丁寧さはこういった背景があったのか…など色々考えさせられました。章の最後に、OSSにはヒントがたくさんあるとありますが、その通りで学ぶことがたくさんあることを教えてくれました

他にも第2特集のオンライン個人認証・本人確認は、ちょうどマイホーム購入のために、ネット銀行での口座開設を行ったこともあり、とてもホットな気持ちで読むことができました。eKYCという用語すら知らなかったので良い機会でした。

執筆のきっかけ

（多分）以下のブログやイベントをキッカケに声をかけていただきました。

このテーマの外部発信はやや人を選ぶと言いますか、それぞれの置かれた状況によってどれくらい注力するかが変わりますし、それなりに経験を積んだITエンジニアの方ならそれなりに一家言を持っていることも多いと思いますので、内容が炎上したらどうしよう…と少し悩みましたが、そのあたりの不安をケアできる内容にすれば面白いかなと思い引き受けさせていただきました。

執筆についての思い

前章にも書かせてもらいましたが、設計ドキュメント周りはそれぞれの開発チームが置かれた環境で大いに文脈が変わってくると思います。今回タイトルに「受託」というキーワードが入っていますが、様々な要件で設計ドキュメントの形式や内容が変化するということを説明するうえで、私の経験をベースに話すと必然、こういった表現になりました。自社プロダクト開発しているソフトウェアエンジニアの方にとっても、例えば品質保証など一部工程を協力会社に移譲している場合は、仕事を依頼するために設計ドキュメントを一定上作り込むと思うので、参考になる話もあるかなと思います。

一般論ですが、受託開発しているエンジニアにとってのプラクティスが、事業会社の内製化チームにとっては重厚すぎて受け入れられないということは私の観測範囲では良く聞くことがありました。逆も然りです。また、同じ受託開発であったとしても、請負契約・準委任ではまたそのバランスも変わってくるため話が通じない場面も多いです。設計書のGit管理の記事を書いた際も、こんなの小さいベンチャーでしか使えないだろうって言われた記憶があります。もしプロジェクトを技術的にリードする立場にある人であれば、その利用できない理由が契約形態なのか記法の揺れが許容できないのかなど、どこにあるのか突き詰めてフィードバックをもらえるともっと建設的な話ができるのになと思いました。今回の寄稿内容にはそのあたりのよくある要因についてもまとめました。

プラクティスとしては、コード生成などの入力として設計ドキュメントを活用したり、なるべくテキストエディタによって編集可能なMarkdown形式で作成し、Git管理する利便性についても説明しています。他の章でも素晴らしいプラクティスが様々書かれていますが、自分たちのチームが抱える前提条件をうまく理解し、取り入れるときに役立つことを祈っています。

また、これからはCopilotなどAI的な設計／コーディング支援を取り入れていくかが品質／生産性向上の鍵かと思いますが、学習しやすくVS Codeで編集可能なMarkdown形式に寄せるメリットは大きいと思います。ドキュメントベースを元にコード／テストデータを生成するナレッジがもっと集まってくれば、そういった観点でどのような設計ドキュメントを作り、逆にこれは省略可能だよねとなる内容が何か分かってくるはずです。最近の進化スピードを見ると2025年、2026年ではまた違う風景になっていると思いますので、楽しみですね。

最後に

社内レビューに投げると、ここはこうしたら？とかもっと体系的に書いた方が良いのでは？といったアドバイスを多数いただきました。すべて適格な内容でまったくその通りなのですが、8ページという枠では全く収まらず、多分ですが倍の分量をもらっても入り切らないくらいアイデアをもらいました。みなさん、ありがとうございました。

また、他の執筆陣の内容がとても面白くて外れなしです。ぜひ陳腐化させない設計ドキュメントを作っていきましょう！