GoogleのDesign Docs文書作成文化（2020）
(industrialempathy.com)- GoogleにおけるDesign Docは、コーディング前に問題の文脈、高レベルの実装戦略、重要な設計判断を整理し、設計コストが低い段階でリスクを減らすための文書
- 文書の価値は完成したコードの説明よりも、トレードオフと代替案を明らかにして、組織が同じ判断根拠を共有できるようにする点にある
- 良いDesign Docには、文脈とスコープ、目標と非目標、実際の設計、検討した代替案、セキュリティ・プライバシー・可観測性といった横断的関心事が、プロジェクトに合わせて盛り込まれる
- 設計がすでに明確だったり、文書が実装手順を並べるだけなら、Design Docの作成・レビューのオーバーヘッドが利点を上回ることがある
- 文書は作成、レビュー、実装中の更新、保守と学習へとつながり、リリース前に設計が変わったなら文書も一緒に更新するのが望ましい
Design Docが担う役割
- GoogleではDesign Docは、ソフトウェアシステムやアプリケーションの主な作成者が、コーディングプロジェクトを始める前に作る比較的非公式な文書
- 高レベルの実装戦略と重要な設計判断を含むが、単なる判断の一覧よりも、なぜその選択をしたのかを示すトレードオフが重要
- ソフトウェアエンジニアリングの目的はコードを生産すること自体ではなく問題解決なので、プロジェクト初期には非構造化テキストのほうがコードより簡潔で理解しやすい場合がある
- Design Docは開発ライフサイクルの中で複数の役割を果たす
- 変更コストが低い段階で設計上の問題を早期に発見する
- 組織内で設計の合意形成を行う
- セキュリティ、プライバシー、可観測性のような横断的関心事を見落とさないようにする
- シニアエンジニアの知識を組織内に広げる
- 設計判断に関する組織の記憶を残す
- 設計者の技術ポートフォリオを要約する成果物になる
Design Docの基本構成
- Design Docに厳密なテンプレートはなく、第一原則は特定のプロジェクトに最も適した形式を選ぶこと
- ただし、よく有用な構成としては、文脈とスコープ、目標と非目標、実際の設計、検討した代替案、横断的関心事、適切な長さに整理できる
-
文脈とスコープ
- 新しいシステムが置かれる環境と、実際に何を作るのかについての大まかな概要を提供する
- 要件文書ではないため簡潔であるべきで、読者が素早く背景を把握できるようにすることに重点を置く
- ある程度の事前知識を前提にしてよく、詳細はリンクでつなげられる
- このセクションは客観的な背景事実に集中すべき
-
目標と非目標
- システムの目標と、場合によってはさらに重要な非目標を短い箇条書きで整理する
- 非目標は「システムがクラッシュしてはいけない」のような目標の単純な否定ではなく、目標になり得たが明示的に除外した項目
- データベース設計でのACID準拠は、それが目標なのか非目標なのかを知るべき良い例
- 非目標であっても、目標達成を妨げるトレードオフがなければ、その属性を提供する解決策を選んでもよい
実際の設計の書き方
- 実際の設計セクションは、概要から始めて詳細へ下っていくべき
- Design Docは、ソフトウェア設計で生じたトレードオフを記録する場所
- 文脈という事実、目標と非目標という要件を土台に解決策を提案し、特定の解決策がなぜ目標を最もよく満たすのかを示す必要がある
- 文書形式の利点は、問題群に合った表現方法を柔軟に選べる点にある
-
システムコンテキスト図
- 多くの文書では system-context-diagram が有用になり得る
- この図はシステムをより大きな技術環境の一部として示し、読者がすでに知っている環境の中で新しい設計を理解できるようにする
-
APIとデータ保存
- 設計対象のシステムがAPIを公開するなら、APIをスケッチするのが一般に望ましい
- 形式的なインターフェースやデータ定義をそのままコピーして貼り付けるやり方は避けるべき
- こうした定義は冗長になりやすく、不必要な詳細を含み、すぐに古くなる可能性がある
- 設計とトレードオフに関係する部分に集中すべき
- データを保存するシステムは、データがどのように、どのようなおおまかな形で保存されるかを扱うべき
- スキーマ定義全体を貼り付けるより、設計判断に関係する部分を説明するほうがよい
-
コードと擬似コード
- Design Docにはコードをほとんど入れないほうがよい
- 新しいアルゴリズムを説明する場合を除けば、擬似コードもめったに使うべきではない
- 設計が実装可能であることを示すプロトタイプがあるなら、適切にリンクできる
制約の度合いが文書の形を変える
- ソフトウェア設計とDesign Docの形に影響を与える主要因の1つは、解決策空間の制約の度合い
- 一方の端には、目標だけがあり解決策は何でも可能なグリーンフィールドのソフトウェアプロジェクトがある
- こうした文書は広い範囲を扱えるが、管理可能な解決策の集合へ絞り込むためのルールを素早く定義する必要がある
- もう一方の端には、取り得る解決策はよく定義されているが、それらをどう組み合わせて目標を達成するかが明確でないシステムがある
- 変更しにくいレガシーシステムかもしれない
- ホストプログラミング言語の制約の中で動作しなければならないライブラリ設計かもしれない
- こうした場合、比較的簡単にできる作業を列挙することはできても、目標達成のためにはそれらを創造的に組み合わせる必要がある
- 複数の解決策がどれも完璧でないなら、文書は特定されたトレードオフをもとに最善の方法を選ぶことに集中すべき
代替案と横断的関心事
-
検討した代替案
- このセクションでは、類似した結果を合理的に達成できた代替設計を列挙する
- 各設計が生むトレードオフと、そのトレードオフが最終的な選択にどうつながったのかに焦点を当てるべき
- 採用されなかった解決策は簡潔に扱ってよいが、このセクションは文書の中で非常に重要
- 読者が気になるかもしれない他の解決策が、プロジェクト目標に照らしてなぜ望ましさが低いのかを示す必要がある
-
横断的関心事
- 組織はこのセクションを通じて、セキュリティ、プライバシー、可観測性のような横断的関心事が常に考慮されるようにできる
- 通常は、各関心事が設計にどのような影響を与え、どう扱われるのかを説明する短いセクションになる
- チームは自分たちの状況でどの関心事を標準にするかを決める必要がある
- Googleのプロジェクトでは、その重要性から別個のプライバシーDesign Docが求められ、プライバシーとセキュリティに関する専用レビューがある
- レビュー完了はプロジェクトのリリース時点までに求められる
- 設計が最初からこれを反映するよう、プライバシー・セキュリティチームとできるだけ早く協業するのがベストプラクティス
- そのテーマの専用文書があるなら、中央のDesign Docは詳細を繰り返さず参照できる
長さと、書かなくてもよい場合
-
適切な長さ
- Design Docは十分に詳細であるべきだが、忙しい人たちが実際に読めるだけの短さも必要
- 大規模なプロジェクトでは約10〜20ページが適切な落としどころに見える
- それよりはるかに長くなるなら、問題をより管理しやすい下位問題に分けるほうがよいかもしれない
- 1〜3ページのミニDesign Docも可能
- 段階的改善やアジャイルプロジェクトのサブタスクで特に有用
- 長い文書と同じ手順を踏むが、より簡潔で限定された問題群に集中する
-
書かなくてもよい場合
- Design Docの作成にはオーバーヘッドがある
- 作成するかどうかは、設計の合意形成、文書化、シニアレビューなどの利点が文書作成コストを上回るかにかかっている
- 中心的な判断基準は、設計上の問題が曖昧かどうか
- 問題の複雑さ、解決策の複雑さ、またはその両方のために曖昧になり得る
- 曖昧でないなら、文書作成プロセスの価値は小さい
- 文書が事実上の実装マニュアルなら、Design Docは不要かもしれない
- 「こう実装する」と述べるだけでトレードオフ、代替案、意思決定の説明がないなら、すぐにプログラムを書いたほうがよかったかもしれない
- 解決策があまりに明確でトレードオフがないなら、文書の価値は低い
- Design Docの作成とレビューのオーバーヘッドは、プロトタイピングや高速な反復に向かないことがある
- アジャイル手法に従うからといって、既知の問題の解決策を十分に考えなくてよいわけではない
- プロトタイピング自体がDesign Doc作成の一部になり得て、「試してみて動いた」という事実は設計選択の強い根拠になり得る
Design Docのライフサイクル
- Design Docのライフサイクルは4段階で構成される
- 作成と高速な反復
- レビュー
- 実装と反復
- 保守と学習
-
作成と高速な反復
- 文書は作成者が単独で書くか、共同執筆者とともに作成する
- その後、問題空間を最もよく知る同僚たちと共有し、素早く反復する
- 同僚たちの明確化の質問や提案が、文書を比較的安定した最初のバージョンへ導く
- Googleにはバージョン管理やコードレビューツールで文書を作ることを好むエンジニアやチームもあるが、多くのDesign DocはGoogle Docsで作成され、共同編集機能が多用されている
-
レビュー
- レビュー段階では、元の作成者や近い協力者よりも広い読者に文書を共有する
- レビューは大きな価値を加え得る一方で、オーバーヘッドの落とし穴にもなり得るため慎重に扱う必要がある
- 軽量なやり方は、文書をより広いチームのメーリングリストへ送り、人々に目を通す機会を与えること
- 議論は主に文書のコメントスレッドで行われる
- 重い形は、作成者が文書をシニアエンジニアの読者の前で発表する正式な設計レビュー会議
- Googleの多くのチームは、この種のレビューのための定例会議を持っている
- こうした会議を待つと開発プロセスが大幅に遅くなることがある
- 最も重要なフィードバックを直接求め、より広いレビューを進行のブロッカーにしないことで緩和できる
- Googleがもっと小さな会社だった頃は、設計を1つの中央メーリングリストに送り、シニアエンジニアが時間のあるときにレビューするのが慣例だった
- このやり方には、会社全体に比較的均一なソフトウェア設計文化を作れる利点があった
- エンジニアリング組織がはるかに大きくなるにつれ、中央集権的なアプローチを維持するのは難しくなった
- レビューの主な価値は、組織の結合された経験が設計に反映される機会を作ることにある
- 特に可観測性、セキュリティ、プライバシーのような横断的関心事を設計が考慮するようにするうえで、レビュー段階は一貫して役立つ
- レビューの中核的な価値は、問題を見つけること自体よりも、変更コストが低い開発ライフサイクル初期に問題が発見されることにある
-
実装と反復
- 追加レビューによって設計に大きな変更が求められる可能性が低いという確信が持てたら、実装を始める時点
- 計画が現実にぶつかると、欠陥、未処理の要件、誤りだと判明した前提が現れ、設計変更が必要になることがある
- この場合、Design Docを更新することが強く推奨される
- 経験則として、設計したシステムがまだリリースされていないなら、必ず文書を更新すべき
- 実際には人々は文書をあまりうまく更新できず、ほかの実務的理由で変更が新しい文書に分離されることも多い
- その結果、1つの一貫した文書というより、修正条項が付いたアメリカ合衆国憲法のような状態になることがある
- 元の文書からこうした修正文書へリンクしておけば、後の保守プログラマがDesign Docの考古学を通じて対象システムを理解する大きな助けになる
-
保守と学習
- Googleのエンジニアが初めて触るシステムに出会ったとき、よく最初にする質問は「Design Docはどこにある？」
- Design Docも他の文書と同様に時間とともに現実とずれる傾向があるが、システムを作った思考過程を学ぶための最もアクセスしやすい入口になることが多い
- 作成者は1〜2年後に自分のDesign Docを読み返してみるとよい
- 何を当てられたかを確認する
- 何を間違えたかを確認する
- 今日なら何を違う形で判断するかを考える
- こうした問いに答える過程は、エンジニアとして成長し、時間とともにソフトウェア設計能力を改善するのに役立つ
いつDesign Docから始めるべきかを判断する
- Design Docは、ソフトウェアプロジェクトの難しい問題を解く際に明確さを得て合意を形成するための良い方法
- 事前調査で避けられたはずのコーディングの行き止まりを減らし、コストを節約できる
- 同時に、作成とレビューには時間がかかるためコストも発生する
- 次の質問を検討できる
- 正しいソフトウェア設計が不確実で、確信を得るために事前に時間を使うのは妥当か？
- すべてのコード変更をレビューできるとは限らないシニアエンジニアを、設計段階に参加させることは役立つか？
- ソフトウェア設計が曖昧または議論の余地があり、組織的な合意が価値を持つか？
- チームはプライバシー、セキュリティ、ロギング、または他の横断的関心事を設計でときどき忘れるか？
- 組織内のレガシーシステム設計について、高レベルの洞察を与える文書が強く必要か？
- これらの質問のうち3つ以上に「はい」と答えるなら、Design Docは次のソフトウェアプロジェクトを始めるうえで良い方法である可能性が高い
1件のコメント
Hacker News のコメント
Google の 設計ドキュメント文化が原因で会社を辞めた
入社直後、別のプロダクト領域で何度もやったことのある比較的些細な作業について、非常に高いレベルでまとめた文書を書いたところ、同僚に別途呼び出されて「ここではそういうやり方はしない」と言われた
私が示した方法は推奨されている方法の小さな変形にすぎなかったが、「この仕事を成し遂げるための、もっと多くの方法を評価しろ」と言われ、理由を尋ねると「幅広く検討したことを示せる」と答えられた
Google には 偽の仕事が確かに存在しており、別のチームに入っていればよかったと思う
Google の文化は、自分自身をまねる カーゴ・カルトになってしまった
Google の後に勤めたいくつかの会社は、昇進プロセスを詳しく議論することを嫌がっていた。人々がそのプロセスに合わせて微細に最適化すると何が起きるかを見ていたからだ
全員が忙しいため、全員と気軽に1対1で話すことはできず、ステークホルダーのレビューをきちんと受けられないと、怒った人たちがやって来てリリースをロールバックさせる可能性がある
この文脈では、設計ドキュメントは情報量の多いトピックのための 非同期コミュニケーションツールである。プロダクトが成功すれば、10年後に参加した人たちともこの文書を通じて対話することになる
今も足を引っ張っている奇妙な判断を説明してくれる2010年のランダムな設計ドキュメントに、何度も救われた。機敏な小規模チームや、複雑さの少ない作業には合わないかもしれないが、エンジニアリング文化には、たとえカーゴ・カルト化していたとしても、たいていそれなりの理由と文脈がある
何かを設計するのに、検討している解決策が1つしかないなら、それは設計が存在しないか、十分に徹底されていないということだ。選択肢とトレードオフこそが設計を形作る要素である
こうした人たちの多くは会社と15年以上仕事をしている外部コンサルタントなので、同じ人たちが同じ作業をしてきたおかげで、すでにある程度の標準はある。それでも「人々が標準に従わなかったらどうなるのか」という藁人形を作ろうと躍起になっている
結果として設計ドキュメントは存在しないか、ひどく古くなっており、会社は毎年同じコンサルタントを 水増しされた費用で雇い続けることになる
今は勤続15年以上の古参 Googler が多いチームにいるが、設計ドキュメントは必要なときにだけ存在する。複数のシステムにまたがる場合や、トレードオフが多く明らかに複雑な場合などだ。それ以外は単に「CL を書け」という感じである
Googleでは設計ドキュメントが昇進パケットに入る重要資料なので、問題が起きているように思う
そのため、ドキュメントは本来の読者であるそのシステムの作業者よりも、昇進委員会を意識して書かれる
新しい会社に入るたびに設計ドキュメントを書き始めようと提案するのだが、そうするとすぐに経営陣に良い印象を与えられる :)
私が読んだ多くのドキュメントは、すでに望む決定を決めておき、ドキュメントの冒頭ではその決定を見せるために作り上げた選択肢を2つ以上付けているように見えた。片方は単純すぎ、もう片方は不要な過剰設計という形で対比させたうえで、合理的に見える案を選ぶ
どの設計ドキュメントを昇進パケットに使うことになるか分からないため、どんなに小さな仕事でもすべて設計ドキュメントとして残す。1ページ設計ドキュメントという概念はあるが、たいてい1ページから数ページへ膨らむ
1週間のプロジェクトにも設計ドキュメントが書かれ、他社ならJIRAチケット1つで済んだような20、30、40ページの設計ドキュメントをレビューしなければならなかったこともある
多くの人が、昇進委員会は「著者が一人で書いたドキュメント」を見たがっていると学んでおり、それが正しいかどうかにかかわらず、この信念があらゆることを遅くし、相互学習を阻害する。1四半期以上も孤立して設計ドキュメントだけを書いているソフトウェアエンジニアも見た
設計ドキュメントでは実際の設計が核心であるべきだが、残りの99%は問題定義である。レビュー中に問題定義を改善しているうちに設計を破棄し、ドキュメントの大半を書き直さなければならなかったことがあまりにも多い
最悪なのは、問題定義を改善した結果、複雑な設計を必要としない単純な解法が明らかになる場合だ。著者は複雑な設計に多くの時間を投じており、歴史的にも多くの委員会がそのような複雑さを昇進の根拠と見なしてきたため、単純な解法に抵抗する
設計ドキュメントに代替案がまったくない場合も見た。ただ、やるべきことや誰かがやりたいことを、労力をかけて書き連ねただけだった
こうなると設計ドキュメントは、ぼんやり見るとバグ追跡システムのように変わっていく。皆が自分の設計ドキュメントに取り組んでいて、バグには取り組まない。バグでは昇進できないからだ
新しいチームに入ると、設計ドキュメントだけ見ればよいというように言われるが、実際には中央で追跡されていないことが多い。多くのチームで設計ドキュメントはチームやプロジェクトの所有ではなく個人の所有であり、他人が貢献していないことを保証できるからで、これもまた昇進委員会のためである
アクセス権のない設計ドキュメントも多いが、極秘だからではなく、単にそうなっているだけだ。チームに設計ドキュメントが2、3個あるわけでもなく、読むべきものが山ほどある。Googleの転職サイクルが約2年という状況では、多くのドキュメントが時の中に消えていく
他社なら、新しいチームに入ってきた人に「必要なことは、クローズされたバグを全部読むか、メインブランチのすべてのコミットメッセージを読めば分かる」と言うのに近い
他の場所なら、昼食後に捕まってチームとホワイトボードの前で数時間、問題を定義していたはずだ。シニアがジュニアに、この種の問題をどう考えるべきかをリアルタイムで教え、素早く反復していたはずだ
たいていはバグ追跡システムに書くか、大きな仕事ならプロジェクトのWikiやフォルダに書いて、全員の所有物にしていたはずだ
上記の問題はいずれも改善可能で、実際に改善しようともしてみたが、文化はゆっくりとしか変わらない。設計ドキュメントという概念自体は良いが落とし穴があり、Googleの多くの人が使っているやり方は答えではない
コストより価値の大きい設計ドキュメントが恋しい
概して、その戦略が効果を上げるのは見たことがない
一方で、文脈提供用として、チームが何をしてきて、何をしており、問題が何なのかなどをまとめた長いドキュメントはあり、そうしたものは長く誇張されがちだった
言及されている会社で働いているが、筆者と同じ経験ではない
設計ドキュメントにはいくつかの種類があるが、その中で有用だったものはなかった。Googleで有用な設計ドキュメントを見たことはまれだ。設計ドキュメントは、手続き志向が強すぎるエンジニアのためのもののように感じる
私が見た種類は、おおよそこんな感じだ。昇進用設計ドキュメントは、何を解決しようとしているのかを説明せず、このプロジェクトがどれほど素晴らしく、会社をより良くするかだけを語る。論理的な結論は、作成者は昇進すべきだということになる
ターボ・エンキャビュレーター設計ドキュメントは、初めて見る用語でいっぱいの技術的な雑談文書で、チームのシニアでなければ理解できない。時にはシニアたちも理解しているのか自信がない
新卒設計ドキュメントは、中身はないが、大学を出たばかりの人が何かを証明しようとして、できるだけ長くした文書だ。情報を伝えず、すでに書いたコードを大きくコピペして70ページほど埋めていることが多い
でっち上げ事実設計ドキュメントは、「誰もが知っている」「みんなそう言っている」であふれている。政治家ほど露骨ではないが、「これは良いプラクティスに従っている」「このソフトウェアは遅い、したがって……」といった調子で自分の設計を押し通す。誰が良いプラクティスを定義したのか、なぜ良いプラクティスなのか、何が遅いのか、測定したのか、エンドユーザーの体感なのかが抜けている
私が見た設計ドキュメントの99%がこうだった。例外はあるが、経験上かなりまれだ。筆者がこの慣行を推しているのは驚きだ。ただ、エンジニアではなくディレクターだったので、その立場では設計ドキュメントが筋が通るのかもしれないし、そういう人たちがどんな価値を提供しているのかはいまだに分からない
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
初期に目についたのは、Google Docsで管理されている設計ドキュメントは、バージョン管理リポジトリにあるものより品質が低い傾向があったことだ。それが作成時期の代理指標だったのか、コードレビューのプロセスがDocsの編集より厳格だったからなのかは分からない
私が大きな設計ドキュメント、おそらく40ページほどのものを書いたときは、慣例どおり手書きのHTMLで作成し、コードレビューシステムを通して進めた。中央のメーリングリストとWebサーバーにも載せたし、3番目の社員からフィードバックをもらえたのも良かった。中央の場所にカテゴリ別に整理されていて、見つけやすかった
当時、設計ドキュメント1本だけで昇進に重要なほど大きな比重を占めていたとは記憶していない。昇進は特定の成果物ではなく、全体としての影響力に関するものであるべきだった。もちろんシステムには大きな欠陥があり、悪い意味で驚くような判断もしばしば出てきたが、その頃は人事評価に最適化された設計ドキュメントを読んだ記憶はない
初期の手書きHTML設計ドキュメントが集まっているWebサイトを見つけられるなら、ざっと見てみることを勧める。当時そのシステムが現役だったなら、より有用に感じられたかもしれない
SmartASSのような古い文書の一部は、基礎となる方程式やモデルについての詳しい説明でいっぱいで、仕組みやなぜそのアプローチを選んだのかを理解するのに大いに役立った。後の自分の設計作業にも影響した。私はディレクターではなくただのエンジニアだったが、実際に役に立った
chromium.orgのWebサイトにリンクされているChromeの設計ドキュメントの中にも、過去に構造を理解する助けになったものがある
ジュニア開発者に解決策を事前に考えさせ、判断を正当化させることができ、シニア開発者がその判断を検証して非同期フィードバックを与えられる
ただし私は常にスタートアップで働いてきたので、30〜40人を超えるエンジニア組織で働いたことはない。ビッグテックは違うだろうが、私の経験は肯定的だった
同様に、他のエンジニアに説明するのに長くかかるなら、少なくとも30分程度でも、時間を節約するために文書を書くべきだ
どうして文書をまったく書く必要がないと考えられるのか分からない
後で昇進の準備をするときは、2番目のカテゴリの文書に十分な文脈を加えて、1番目のカテゴリにすることになる
ドキュメント化は一般には良いことだが、このアプローチには欠陥があるように見える
「コーディングプロジェクトに着手する前に」ソフトウェアシステムやアプリケーションの主な作成者が比較的非公式な文書を作るというが、設計そのものがコーディングプロジェクトであり、両者は同じ仕事だ
コードをコミットする前に紙の上で設計をすべて解き切れるという考えは間違っている。設計ドキュメントのアプローチも、実際には初期に少しコードを書く必要があることは認めているが、それを「設計の実装可能性を示すプロトタイプ」として厳密に区切ろうとする
事前設計ドキュメントの大きな特徴は、本格的なコーディングの前に人々がケチをつける、つまりレビューできるよう許可することだ。私の経験では、そうすると文書はますます多くの但し書きや無意味な代替案の議論で膨らみ、設計ドキュメントというより「お願いだからもうこれを作らせてくれ」ドキュメントになる
方向転換が必要な重要なアーキテクチャ上の問題があるなら、詳細な設計ドキュメントを作ってから撃墜されるより、事前に適切な人たちと話し合い、協業する方がよい
「比較的非公式な文書」という考えにより近い形を保ち、進めながら文書を更新するなら、実際に有用になり得る。動くシステムと有用な文書を一緒に作れるからだ。ただしそれは設計ドキュメントというより、継続的で協調的なプロセスの一部としてドキュメント化することに近い
Googlerです。論文も何本も出しましたが、以前は設計ドキュメントを書くのが嫌いでした。数年前から、それが自分にもたらす主な利点に気づきました。
アイデアの目先の部分を頭の中からいったん空にして、より深い部分や生産的な検討へ進めるようにしてくれます。
欠陥がよりよく見えるようになり、特に自分自身に対して見えやすくなります。
考えを共有しやすくなり、特に別オフィスの人たちに共有しやすくなります。彼らはたいてい非常によいフィードバックをくれます。
いきなりコーディングを始める場合よりも、必要な作業量をはるかによく把握できるようになります。
コーディング前に学ぶべきこと、隣接するシステムや適切な技術選定などを、たいてい明らかにしてくれます。
昇進にも良いのは確かですが、成功したプロジェクトのほうがさらに良いです。自分のドキュメントが役に立つとよく言われるので、何か正しいやり方を見つけたように感じています。
実際に効果はあるのか？ 代替案より優れているのか？ その議論はどこにあるのか？
Amazonで働いていたとき、設計ドキュメント文化は素晴らしかったです。次の職場はGoogleのエンジニアリング文化やサンフランシスコの一般的なスタートアップ文化を借りてきたようでしたが、設計ドキュメントの手続きは役に立たない冗談のようでした。
より広い仕事文化と組み合わさった一つの仕組みです。一人で働いているならぜいたくな練習にすぎませんが、巨大なチームならチーム全体のより多くの専門性を活用でき、文書としての役割も果たします。
失敗パターンはいくつかあります。結果より成果物を重視するのは典型的な不整合です。昇進のために40ページの文書を書くようなケースですが、深いエンジニアリングではなく文章をつなぎ合わせられることを証明する、かなりジュニアな場合でなければうまく機能しません。
一人で働くチームには過剰だという点もあります。他の小規模チームなら、課題、たとえばJiraと、アイデアをすり合わせる別セッションだけでも十分にコミュニケーションできます。
エンジニアも、効果的な設計ドキュメントの書き方についてオンボーディングされる必要があります。最初の試みがすぐに称賛されなかったからといって落胆している上位コメントは、その兆候かもしれません。
コードについて文章を書くのは難しく、通常HNではこうした練習は称賛されます。チームで働いているなら、自分の仕事が常に共有可能な文書で説明したり深く考えたりする必要のないものばかりだと感じるときは注意すべきです。
大口投資家が身分を隠して数週間Googleのエンジニアとして働いてみたら、すぐにSundarの解任を求めるアクティビスト投資家になるでしょう。
Googleの設計ドキュメント文化によって浪費されている人間の潜在力の規模は、ほとんど理解しがたいほどです。
開発の大半はそのまま進み、たまにCLを正当化しやすくするために文書を急いで書き上げるだけです。
10件に1件くらい、誰かがやりすぎているのを見ますが、平均的なソフトウェアエンジニアにとっては大きな時間の無駄ではありません。
できるだけ多くのお金を燃やしたいなら、会社をまさにこのように設計すると思います。
設計ドキュメント文化は、全員を自分の仕事に対する正当化レイヤーへ押し込む傾向があります。正当化の文化は、同僚によって文化として強化されているとしても、イノベーターにとってかなり抑圧的なパターンです。
このシステムは、ビジョンのある試みや野心的なプロジェクトを妨げる傾向があります。合意中心でない努力は抑え込まれ、「許された規範の外」を考えると集団から罰せられます。
こうしたシステムは集団思考を生み、「私たちの働き方」という伝統中心の性格は、別のやり方で働くことがキャリア上のリスクになる状況を本質的に強制します。
シリコンバレーには「アジャイル」や「デザイン思考」という用語で包まれた決まり文句に頼る企業文化があらゆる形で存在し、たいていは「正しいやり方」のふりをした制度化に近く、そのキャンパスが到達したエンジニアリング・カルト文化の変種を社会的に強制する付加要素が伴います。
Googleで働くのはとても快適だったにもかかわらず、キャリアの制約になると言って去った人を数え切れないほど見てきましたし、少数ではありません。
私がそこで感じたフラストレーションを正確に表現してくれました。それでも、あの報酬はまた欲しいとは思います。
アジャイルについて言えば、私は約20年前にeXtreme Programmingの形でアジャイルに触れましたが、今日のSCRUMやその模倣品というカーゴカルトとはまったく違っていました。
結局のところ、開発者に創造的な力を与え、管理者が方法に口を出せないようにし、仕事を成し遂げさせる原則の束でした。その代わり、顧客には何を、いつ、どの程度行うかを言う権限を与えます。
開発者が自分で見積もり、「必要でないものは作らない」が原則です。大きな事前設計はなく、リファクタリングとテスト、アーキテクチャと設計は別個のストーリーやタスクではなく、標準的なベストプラクティスとして継続的なオーバーヘッドに含まれます。
計画ミーティングは同僚が部屋で認識を合わせる場で、ストーリーはホワイトボード上の付箋に、最小限の非技術用語で表現されます。スタンドアップは実際に人々が輪になって立ち、他の人が関心を持つかもしれない程度にごく短く更新を共有するものであって、今日出勤したことを証明したり見せびらかしたりする儀式ではありません。
このシステムでは、設計は専門家たちの創造的な集団が一緒に働く中で生まれる性質のものです。設計ドキュメントを排除するわけではなく、アーキテクチャの議論も引き続き含まれますが、明示的なPRD/設計ドキュメント手続きは要求しません。
そういう場所でまた働いてみたいです。Googleは正反対で、すべてに時間がかかりすぎました。
こういう偽りの「私たちはとても賢い」式の振る舞いも無駄仕事の一形態です。会社は実際に動く製品に集中し、それによって自らを評価すべきです。
これも別の Googler です
Google の設計文書が役に立たないという良いコメントはすでに多いですが、問題だと感じる観点をもう一つ付け加えたいです
設計文書は言及されているように昇進資料なので、大量の余計なものを生みます。ところが、実際のドキュメント化の代わりになっているようにも見えます
どの設計文書も完成した瞬間にほとんど古くなってしまいますが、チームは文書を書き直す代わりにその設計文書を参照します。結果として、Google のドキュメントはかなり悪く、古くなっています
正直なところ、「やらなかったこと」について20ページ書くより、実際に存在するものをどう使うかを説明する2ページの利用ガイドを書くことが昇進資料になったほうが、はるかに良かったでしょう
実際の文書は見られますか？ ソフトウェア設計プロセスの文書は、最も厳重に守られている秘密のように見えます。ケーススタディに使える実際の文書を見たことがありません
Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps
例: https://rfd.shared.oxide.computer/rfd/0177
メイン索引: https://rfd.shared.oxide.computer