了解设计文件的参考链接集合

3 年 ago

宇, 华

1 minute

由于我也打算开始制作设计文档，所以我进行了信息收集，以了解设计文档究竟是什么，并总结了一些自己的思考。

设计文件概述

Googleのソフトウェアエンジニアがどのように開発しているのかという発表で、プロダクト開発の流れの中でデザインドキュメントを利用していることが説明されている
Why(背景や目的)、How(おおまかな設計、コードを見てわかることは書かない)、Who(メンバ、誰にコンタクトすればそのプロダクトについて知れるか)、セキュリティやプライバシーに関する考慮、テストやモニタリングをコーディング前に記述する。開発を進める中でできるだけ乖離しないように修正する。
この発表内容に関する聴講者のメモ: Google のソフトウェア・エンジニアリング

[2009-11-17] Google の Design Doc について

Software Engineer in Googleの発表や複数のOSSにおけるデザインドキュメントを引用した上で、自分1人で開発するプロジェクトにおけるデザインドキュメントに書くべき内容のまとめ
コードを書く前に文章化することで問題を整理して目標を明確化する。また、ソフトウェアのメンテナンス性・再利用性向上に役立てる。
依存ライブラリやバージョンを書くべきかは疑問だが、todoのように今はやらないことを整理しておくのはよさそう。

[2016-06-21] 残業も減らせる!? 上級エンジニアになるためのDesign Doc超入門

ソフトウェア開発におけるコミュニケーション手段の1つとして、利用ユーザ向けではなくその開発者・技術視点としてのドキュメントとしてのデザインドキュメントの紹介
少し古い記事だからかもしれないがあまり納得できない。思考の整理という意味ではデザインドキュメントである必要はないし、作業時間を短縮する説明にもなっていない。

[2018-12-16] #1: デザインドキュメントを書こう

マイクロサービスでは複数のサービスと連携するため、サービスの分割や全体設計が重要であり、これを十分に議論するためにデザインドキュメントを作成するという考え
確かに、マイクロサービスのように変更が他のチームなどに影響する場合は変更の必要性も認識される必要があり、デザインドキュメントが有効に機能しそう

[2020-07-06] Design Docs at Google

GoogleエンジニアによるGoogleのデザインドキュメント詳細
デザインドキュメントを書くことによるメリットや何を書くか、どのくらい書くか、何を書かないかがまとまっており非常に参考になる
その日本語訳: [2020-08-03] 【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」

[2021-03-04] Design Docs のいけすかなさ

他の参考資料とは異なりデザインドキュメントの欠点や課題について議論している。
デザインドキュメントが上手くいかない点や過度に期待されている点、点などが指摘されている。

[2021-06-30] 緩やかに死んでいくシステム

Cloud Native Lounge #2における発表(発表スライドおよび発表録画)
ソフトウェアを継続的に開発するために必要なものはいくつもあるが、そのうちのドキュメントに焦点を当て、AWSにおけるデザインドキュメントを用いたメリットの紹介
継続的な改善のためにはなぜ現在の設計になっているかが重要で、これをドキュメントとして残すという考えがわかりやすい

Design Docs at Google 对于什么是设计文件有详细的说明，但关于为什么需要设计文件，逐渐死去的系统给出了令人信服的解释。

为了让人们理解为什么需要开发某个功能，并记录哪些问题进行了考虑，哪些问题没有考虑，需要创建设计文件。将传达开发动机的部分在着手开发之前记录并分享，并在理解后进行PoC，记录讨论结果以及最终为何做出这样的设计。如果代码审查时有设计文件，就可以更容易地了解为什么选择这样的实现方式，并且在将来的功能改进时，如果有设计文件，就不需要再进行相同的讨论，而且可以更容易理解相关功能的背景。

反过来，在开发动机、实现方法和其他权衡已经明确的情况下，就不需要创建设计文件。在沟通和达成共识容易的情况下，没有必要专门创建设计文件。然而，确定在什么情况下不需要设计文件似乎比创建设计文件本身更困难。

其他文件

ADR即代表股权右证明(ADR)，是一个在美国证券市场上交易的股权证明，代表在国外市场发行的股票。

ADRとデザインドキュメントの違いを明確に延べている資料は見付けられなかった
ADRは1つの判断につき1つのファイルを書くことを推奨している例や推奨記述項目が少ない例が多く、より書きやすく(読みやすく)することを重視している。デザインドキュメントは複数の選択肢(判断)を踏まえた最終的な判断を記載することを推奨している例やアーキテクチャに加えてセキュリティやテスト、運用など複数の内容を記載することを推奨している。

参考

Homepage of the ADR GitHub organization

導入した記録ではなく導入“しなかった”記録を残す LADRによるアーキテクチャ意思決定記録のすすめ

インタビュー形式なのでLADRに対する期待などがわかりやすい。これだけ読むとデザインドキュメントとの違いがわからなくなる。

Architectural Decision Records（ADR）実践備忘録

事例

Ubie事例: [2021-06-16]ユビーが長期に渡ってソフトウェアを進化させ続けるためのドキュメンテーションプラクティス

スタディサプリ事例: [2021-04-05]〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録

elastic事例: Elastic Cloud on Kubernetes (ECK)

ADR（アーキテクチャ判断記録）は、デザインドキュメントと同様に、なぜそのような行動が起こったのかを記録するためのドキュメントですが、1つのファイル・意思決定が小さくなると仮定しています。デザインドキュメントは、なぜシステムがそのように設計されたのかに焦点を当てていますが、ADRは開発者がなぜそのような判断を下したのかに焦点を当てており、ドキュメントを残す目的が多少異なると考えられます。例えば、利害関係者が多くて判断を下すことが難しい場合には、ADRの方がより有効となる可能性があります。

Canton Humen District in the Pearl River Delta Region.

[2019-11-11]はじめてのPRD

プロダクトの軸を定めるために必要なドキュメントとして紹介。リーンキャンバスやインセプションデッキとの比較によりイメージがついた

广东省的目的、内容和设计文档完全不同。

规范书

所谓的规范文件。简称。

设计文档的具体示例

WebKitにおけるWebSocketの実装に関するデザインドキュメント。
かなり細かく、具体的なコードまで記載されているのでこれだけ読むと関数コメントからdoxygen等でドキュメント生成でよいのではと思ってしまう。10年以上前の事例なので今と状況が違うから、と判断してよいのだろうか？

Chromium Design Documents

Chromiumにおけるデザインドキュメント一覧。かなり大量にあるので参考になる？

[2019-12] Prometheus Exemplars

Prometheusのプルリクに関するデザインドキュメント。 e34.fmで紹介されていた。
最近のOSSでのデザインドキュメント事例という意味で参考になる。他のプルリクでもデザインドキュメントが記載されているものもあるが、かなりフォーマットや記載内容にばらつきがある。OSSだから？