17
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@thaim

デザむンドキュメントを知るための参考リンク集

17
Posted at

自分もデザむンドキュメントを始めようず思ったので、デザむンドキュメントずは䜕かを知るために情報収集した結果ず簡単な自分の考えのたずめ。

デザむンドキュメント抂芁

  • [2007-06-01] Software Engineer in Google - Google Developer Day Tokyo 2007
    • 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
  • [2021-03-04] Design Docs のいけすかなさ
    • 他の参考資料ずは異なりデザむンドキュメントの欠点や課題に぀いお議論しおいる。
    • デザむンドキュメントが䞊手くいかない点や過床に期埅されおいる点、点などが指摘されおいる。
  • [2021-06-30] 緩やかに死んでいくシステム
    • Cloud Native Lounge #2における発衚(発衚スラむド および 発衚録画)
    • ゜フトりェアを継続的に開発するために必芁なものはいく぀もあるが、そのうちのドキュメントに焊点を圓お、AWSにおけるデザむンドキュメントを甚いたメリットの玹介
    • 継続的な改善のためにはなぜ珟圚の蚭蚈になっおいるかが重芁で、これをドキュメントずしお残すずいう考えがわかりやすい

デザむンドキュメントが䜕なのかに぀いおは Design Docs at Google が詳しいが、なぜデザむンドキュメントが必芁なのかに぀いおは 緩やかに死んでいくシステム が玍埗感が高かった。
開発する機胜に぀いお、なぜその開発が必芁なのかを玍埗しおもらうために、たた䜕を怜蚎しお䜕を怜蚎しなかったのかを残すためにデザむンドキュメントを䜜成する。開発するモチベヌションを䌝える郚分は開発着手前に蚘茉しお共有し、それが䌝わったらPoCをしながら怜蚎結果を残しおなぜ最終的な蚭蚈になったのかを残す。プルリクレビュヌ時にデザむンドキュメントがあればなぜこの実装なのかわるのでレビュヌしやすいし、埌日機胜改修時にデザむンドキュメントがあれば同じ怜蚎をしなくお枈むし、察象機胜のコンテキストが理解しやすくなる。
逆に開発するモチベヌションや実装方法、その他トレヌドオフが明確な堎合はデザむンドキュメントを䜜成する必芁がない。コミュニケヌションや合意圢成が容易な堎合はわざわざデザむンドキュメントを䜜成する必芁はない。ずはいえ、どういった堎合にデザむンドキュメントが䞍芁かは単にデザむンドキュメントを䜜成する以䞊に難しそう。

その他のドキュメント

ADR

デザむンドキュメントず同じくWhyを残すためのドキュメントであるが、1぀のファむル・意思決定が小さくなるこずを想定しおいる。これは、デザむンドキュメントは察象システムがなぜそのような蚭蚈になっおいるか、ADRは開発者がなぜそのような刀断を䞋したか、に焊点を圓おおおりドキュメントを残す目的が倚少異なる䟋えば、利害関係者が倚くお刀断を䞋すこずが難しい堎合にADRがより有効になる

PRD

  • プロダクト芁求仕様曞(Product Requirements Document)。
  • デザむンドキュメントやADRず合わせお䜜成するドキュメント䟋ずしお挙げられおいたが、こちらは技術的な内容ではなく䞻にPdMが䞭心ずなっお䜜成し、䜕(What)を䜜るのかに焊点を圓おたドキュメント。
  • 参考
    • [2019-11-11]はじめおのPRD
      • プロダクトの軞を定めるために必芁なドキュメントずしお玹介。リヌンキャンバスやむンセプションデッキずの比范によりむメヌゞが぀いた

PRDは䜜成する目的も内容もデザむンドキュメントず明確に異なる。

仕様曞

いわゆる仕様曞。略。

デザむンドキュメントの具䜓䟋

  • [2009-09-02] WebKit WebScoket design doc
    • WebKitにおけるWebSocketの実装に関するデザむンドキュメント。
    • かなり现かく、具䜓的なコヌドたで蚘茉されおいるのでこれだけ読むず関数コメントからdoxygen等でドキュメント生成でよいのではず思っおしたう。10幎以䞊前の事䟋なので今ず状況が違うから、ず刀断しおよいのだろうか
  • Chromium Design Documents
    • Chromiumにおけるデザむンドキュメント䞀芧。かなり倧量にあるので参考になる
  • [2019-12] Prometheus Exemplars
    • Prometheusのプルリクに関するデザむンドキュメント。 e34.fmで玹介されおいた。
    • 最近のOSSでのデザむンドキュメント事䟋ずいう意味で参考になる。他のプルリクでもデザむンドキュメントが蚘茉されおいるものもあるが、かなりフォヌマットや蚘茉内容にばら぀きがある。OSSだから
17
15
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
17
15

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?