ソフトウェアの開発案件では設計書・仕様書などのドキュメントを作ることがよくある。
ドキュメントを作る際、フォーマットや内容の抽象度（どこまで具体的に詳細を書くか。粒度と呼んだりもする。）で統一感を求められることが多々ある（特に、開発スタイルがウォーターフォール型の受託開発の場合に多い）が、それって意味あるのだろうか？とよく疑問に思う。
ドキュメントの種類や目的にもよるだろうけれど、個人的にドキュメントには統一感はそれほど必要ないんじゃないかと思う。開発しているプロダクトのUIデザインとソースコードや設計方針に関しては、統一感はあって欲しいと思う。UIデザインの統一感はユーザーの使い勝手に直接影響があるし、ソースコードや設計の統一感は保守性に影響がある。それ以外の成果物に関しては、一度リリースが終わってしまえば統一感がないことで困る場面はあまりないんじゃないかと思う。
設計書のような実装時に参照する系のドキュメントに関して言えば、むしろ、実装する人が誰なのかによって抽象度は意図的に変えるべきでは？とも思ったりもする。
実装者によって設計書の抽象度を変える
まず、設計者と実装者の開発スキルが「設計者の開発スキル < 実装者の開発スキル」となっている場合（意外とよくあるケースだと思う）、設計書はできるだけ抽象的にして、あまり具体的な実装方法は書かない方が良いと思う。
実装者の開発スキルが高い場合、具体的な実装方法は実装者に任せた方が、設計者が思うよりもより良い方法で実装してくれる可能性が高い。設計者が下手に具体的な実装方法まで指定してしまうと、あまり良い実装方法ではなくなってしまい、プロダクトの品質を落としてしまう可能性もある。
「設計者の開発スキル > 実装者の開発スキル」となっている場合、品質を担保するためには、設計者がある程度具体的に実装方法を示した方が良いかもしれない。
ただ、この場合も、設計者と実装者の関係性によって設計書の抽象度は調整した方が良いと思う。
まず、実装を外部に委託しているなどの都合で、実装者が他社の開発者で面識があまりないとか、スキルのレベルがどの程度か分からないという場合、実装方法まである程度具体的に示した方が、心理的に安心できる。
また、他社の開発者に実装を任せる場合、育成の観点を考える必要がないことからも、設計書はある程度具体的でも良いかと思う。SESのような形で外部の人に作業している場合も、育成まで考えて作業する場面は少ないかと思うので、設計書は具体的でも良いかもしれない。
実装者が自社の開発者である場合、育成を兼ねているかどうかで設計の在り方は変えるのが良いと思う。 開発者の育成も兼ねている場合は、設計書の内容をある程度抽象的にして、自分で実装方法を考える余地を残しておく方が、開発者としての成長にはプラスになる。
特に、自分で一からロジックを考えて実装するのが好きなタイプの場合、設計者が細かい実装方法まで指定すると開発者のモチベーションを低下させてしまうので、設計書の内容は意図的に抽象的にしておいた方が良い。開発者が自分でロジックを考えるのが苦手なタイプの場合は、ヒントを混ぜ込んだり、参考になるサイトを載せたりして、ある程度土台がある状態を作ってから考えさせる方が良いと思う。
設計者と実装者が同一の場合は、本音を言えば設計書を作る必要もないと思う。
ソフトウェア開発において、プロダクトの価値や品質を高めるうえで設計という工程そのものは欠かせない。ただ、「設計」と「設計書作り」はイコールではない。設計書があるからと言って適切な設計が行われているとは限らないし、設計書がないからと言って設計が雑というわけでもない。
設計が適切かどうかは、保守性の高いコードや構造でもって要件を満たすたための実装方針を描けているかどうかが重要。設計者と実装者が同じ人の場合、設計書は適切な設計を整理するための箇条書きメモくらいで良いんじゃないかと思う。
まとめると、設計書は
- 設計者と実装者の関係性
- 設計者と実装者の開発スキルの差
- 実装者が育成の対象か
- 育成対象者がどんな性格か
などの要素によって抽象度を変えた方が良いと思う。
ドキュメントは負債
そもそもドキュメントはいずれ負債になる可能性が高い。
設計書・仕様書などのドキュメントは、プロジェクトが開始して一からプロダクトを作り始める段階ではそれなりに役に立つが、一度リリースして運用保守が始まってからはあまり役に立たない。
リリース後に頻繁に機能改善が入るプロダクトの場合、設計書とコードの二重管理が面倒になり、途中からドキュメントの方がメンテナンスされなくなってしまうケースがほとんど。運用期間が長ければ長いほど、正しい仕様を知るためには実際に動いているコードを読むか知見のある人に直接聞くしかない、という状況になるので、設計書がそもそも役に立たない。
設計書などのドキュメントをユーザー企業や顧客企業に納品しなければいけない、という現場もあるけれど、納品されたドキュメントが役に立った、という話は私の経験上誰からも聞いたことがない。操作マニュアルですら、ユーザーによっては直接聞いた方が早いと言う理由でほとんど使われないケースも多い。
そのような、いずれ役に立たなくなる成果物に対して、統一感を持たせるための修正に時間をかけるのは正直無駄な作業であると思う。そこに時間をかけるのであれば、少しでもユーザーに価値が届く機能の開発を優先すればよいのなと思う。
レイアウトを整えられるから、統一感を出したくなる？
そもそも、レイアウトをデザインできるツールでドキュメントを作るから、統一感を持たせたくなるのかもしれない。
Excelのようなレイアウトを細かくデザインできる（できてしまう）ツールで一度ドキュメントを作ってしまうと、そのほかのドキュメントも同じフォーマットにしないと統一感がなくて何となくモヤモヤした気持ちになるのは、分からなくもない。ただ、それで後からレイアウトの統一感を指摘されたら面倒なので、ドキュメントを作るなら最初からレイアウトを細かくデザインできないツールを選びたい。
ドキュメントをマークダウンのような、テキストベースにしておけば、レイアウトの統一感などあまり気にする必要がなくなるし、仮にまとめて修正したい場合も正規表現やスクリプトでまとめて修正がしやすい。
そもそも、生成AIを使ってどうやって生産性を上げていくかという時代において、AIライクでないツール（Excelとか）を使っている時点で時代に取り残される感は否めない。
最初からテキストベースで作成するようにしておけば、レイアウトの統一感とか気にしなくても良いし、AIとの相性も良い。ということで、ドキュメント作成時はそもそもレイアウトをつくりこめるツールを使わない方が良いと思う。
完璧主義の弊害
たぶん日本は全体的に完璧主義の文化が強い傾向にあると思う。（モノづくりでの成功体験の名残り？）
その影響で、ドキュメントのような、ユーザーへの価値提供に直接関係のない成果物でも、完璧を求める傾向が強いのかもしれない。
日本のモノづくりにおいて完璧主義は、製品の品質を上げて世界に良い影響を与えたかもしれないけれど、ソフトウェア開発において完璧主義を持ち込むのは多分あまり良くない。
完璧主義の思想があると、バグや障害が少しでもあるとダメという雰囲気になる。もちろん障害は起きない方が良いし、バグもない方が良い。ただ、バグがあった場合は基本的に修正しなければいけないという風潮は、必ずしもプロダクトの価値を高めるとは限らない。
仮に発生頻度が低く、ユーザーへの影響も少ないようなバグが見つかった場合、その修正に工数を割くぐらいなら、ユーザーへの価値が高い機能の開発に注力する方が全体としてプロダクトの価値は高くなる可能性が高い。
また、些細なバグを修正するのに、コードに大幅な変更を加えて保守性や可読性が悪くなってしまったとすれば、ユーザーから見た品質は向上しているように見えて、開発者から見た技術的負債が増えてトータルでのプロダクトの価値は低くなっている可能性もある。
完璧主義は、見た目上の品質を上げるのには役立つかもしれないが、品質を上げることを優先するがゆえに、本当に大事な優先順位を見失って、プロダクトの価値向上を妨げる要因となっているようにも感じる。その延長線上で、ドキュメントに対しても完璧を求める現場が多いのかもしれない。
たぶん、日本でDXがあまり進まないのも、いつまでもウォーターフォール型の開発がなくならないのも、完璧主義が邪魔をしているんじゃないかと思う。
まとめ
結局のところ、ドキュメントに統一感を持たせるかどうか、そしてどこまで統一するのかは
- ドキュメントの目的は何なのか
- 自社開発でない場合は顧客との契約内容がどうなっているか
- 案件内での優先順位として何に重きが置かれているか
などの要因で決まるのだろうと思います。ドキュメントに統一感があること自体は悪いことではないし、むしろ統一されているならそれに越したことはないでしょう。ただ、ドキュメントに統一感を出すことにそれなりのコストがかかる作業にもかかわらず、優先順位が高めに設定されているとするなら、優先順位が適切かどうかは改めて考えてみても良いかもしれません