優れたソフトウェア設計ドキュメントの書き方

ソフトウェアエンジニアとして、私は設計ドキュメントの読み取りと書き込みに多くの時間を費やしています。これらのドキュメントを何百も読んだ後、優れた設計ドキュメントとプロジェクトの最終的な成功との間に強い相関関係があることを直接目にしました。

この記事は、デザインドキュメントを優れたものにする理由を説明するための私の試みです。

この記事は4つのセクションに分かれています。

  • 設計ドキュメントを書く理由
  • 設計ドキュメントに含めるもの
  • どのようにそれを書くために
  • その周りのプロセス

なぜデザインドキュメントを書くのですか?

設計ドキュメント(技術仕様とも呼ばれます)は、問題の解決方法の説明です。

コーディングに取り掛かる前に設計ドキュメントを書くことが重要である理由については、すでに多くの記述があります。だから私がここで言うのは:

設計ドキュメントは、適切な作業が確実に行われるようにするための最も便利なツールです。

デザインドキュメントの主な目標は、デザインについて考え、他の人からフィードバックを集めることを強制することで、より効果的にすることです。設計ドキュメントのポイントは、他の人にシステムについて教えたり、後でドキュメントとして使用したりすることだとよく考えられます。これらは有益な副作用になる可能性がありますが、それ自体が目標ではありません

一般的な経験則として、1エンジニア月以上かかる可能性のあるプロジェクトに取り組んでいる場合は、設計ドキュメントを作成する必要があります。しかし、それだけではありません。小さなプロジェクトの多くは、ミニデザインドキュメントからも恩恵を受ける可能性があります。

すごい!あなたがまだ読んでいるなら、あなたはデザインドキュメントの重要性を信じています。ただし、異なるエンジニアリングチーム、および同じチーム内のエンジニアでさえ、設計ドキュメントの記述方法が大きく異なることがよくあります。それでは、優れた設計ドキュメントの内容、スタイル、およびプロセスについて説明しましょう。

設計ドキュメントに何を含めるか?

設計ドキュメントには、問題の解決策が記載されています。それぞれの問題の性質は異なるため、当然、設計ドキュメントを異なる方法で構成する必要があります。

まず、少なくとも検討する必要のあるセクションのリストを以下に示します。次の設計ドキュメントに含める:

タイトルと人

デザインドキュメントのタイトル、著者(このプロジェクトに取り組むことを計画している人々のリストと同じである必要があります)、レビューアドキュメントの(これについては、以下の「プロセス」セクションで詳しく説明します)、およびこのドキュメントが最後に更新された日付。

概要概要

会社のすべてのエンジニアが理解し、ドキュメントの残りの部分を読むことが役立つかどうかを判断するために使用する必要がある高レベルの要約。最大3段落にする必要があります。

環境

手元にある問題の説明、このプロジェクトが必要な理由、このプロジェクトを評価するために人々が知っておくべきこと、および技術戦略、製品戦略、またはチームの四半期目標にどのように適合するか。

目標と非目標

目標セクションは次のようにする必要があります。

  • プロジェクトのユーザー主導の影響を説明します—ユーザーが別のエンジニアリングチームまたは別の技術システムである可能性があります
  • 指標を使用して成功を測定する方法を指定します—これらの指標を追跡するダッシュボードにリンクできる場合はボーナスポイント

非目標は、修正しない問題を説明するためにも同様に重要であるため、全員が同じページにいます。

マイルストーン

測定可能なチェックポイントのリスト。これにより、PMとマネージャーのマネージャーはそれをざっと見て、プロジェクトのさまざまな部分がいつ行われるかを大まかに知ることができます。プロジェクトの期間が1か月を超える場合は、プロジェクトをユーザー向けの主要なマイルストーンに分割することをお勧めします。

カレンダーの日付を使用して、無関係な遅延、休暇、会議などを考慮に入れます。次のようになります。

Start Date: June 7, 2018

Milestone 1 — New system MVP running in dark-mode: June 28, 2018

Milestone 2 - Retire old system: July 4th, 2018

End Date: Add feature X, Y, Z to new system: July 14th, 2018

[Update]これらのマイルストーンの一部のETAが変更された場合は、ここにサブセクションを追加して、利害関係者が最新の見積もりを簡単に確認できるようにします。

既存のソリューション

現在の実装を説明することに加えて、ユーザーがこのシステムをどのように操作するか、および/またはデータがどのように流れるかを示すために、高レベルのサンプルフローもウォークスルーする必要があります。

ユーザー物語これを組み立てるのに最適な方法です。システムには、さまざまなユースケースを持つさまざまなタイプのユーザーがいる可能性があることに注意してください。

提案された解決策

これをテクニカルアーキテクチャセクションと呼ぶ人もいます。繰り返しになりますが、これを具体化するためにユーザーストーリーをウォークスルーしてみてください。多くのサブセクションや図を自由に含めてください。

最初に全体像を提供し、次にたくさん記入します詳細。これを書ける世界を目指して、無人島で休暇をとると、チームの別のエンジニアがそれを読んで、説明したとおりにソリューションを実装できます。

代替ソリューション

上記の解決策を考え出すときに、他に何を考慮しましたか?代替案の長所と短所は何ですか?独自のソリューションを構築するのではなく、この問題を解決するサードパーティのソリューションを購入すること、またはオープンソースのソリューションを使用することを検討しましたか?

テスト容易性、監視およびアラート

私はこのセクションを含めるのが好きです。なぜなら、人々はこれを後付けとして扱ったり、すべて一緒にスキップしたりすることがよくあり、ほとんどの場合、後で物事が壊れて、方法や理由がわからないときに噛むために戻ってきます。

チーム間の影響

これは、通話と開発運用の負担でどのように増加しますか?

どれくらいの費用がかかりますか?

システムに遅延の回帰を引き起こしますか?

セキュリティの脆弱性が明らかになりますか?

いくつかの悪影響と副作用は何ですか?

サポートチームはこれをどのように顧客に伝えますか?

未解決の質問

確信が持てない未解決の問題、読者に検討してもらいたい論争の的となる決定、将来の作業の提案など。このセクションのほっぺたの名前は「既知の未知数」です。

詳細なスコープとタイムライン

このセクションは主に、このプロジェクトに取り組んでいるエンジニア、技術リーダー、およびマネージャーだけが読むことになります。したがって、このセクションはドキュメントの最後にあります。

基本的に、これはプロジェクトの各部分を実行する方法と時期の内訳です。正確なスコーピングには多くのことが含まれているため、この投稿を読んでスコーピングについて詳しく知ることができます。

また、設計ドキュメントのこのセクションを進行中のプロジェクトタスクトラッカーとして扱う傾向があるため、スコープの見積もりが変更されるたびにこれを更新します。しかし、それは個人的な好みです。

書き方

今、私たちが話したことをどのような良いデザインドキュメントになり、執筆のスタイルについての話をしましょう。これはあなたの高校の英語の授業とは違うことを約束します。

できるだけ簡単に書く

あなたが読んだ学術論文のように書こうとしないでください。それらは、ジャーナルの査読者を感動させるために書かれています。ドキュメントは、ソリューションを説明し、チームメートからフィードバックを得るために作成されています。以下を使用して明確にすることができます。

  • 簡単な言葉
  • 短い文章
  • 箇条書きおよび/または番号付きリスト
  • 「ユーザーアリスが自分の銀行口座を接続してから…」などの具体的な例

たくさんのチャートや図を追加する

チャートは、いくつかの潜在的なオプションを比較するのに役立つことが多く、図は一般にテキストよりも解析が簡単です。ダイアグラムを作成するためにGoogle図形描画で幸運を祈りました。

上級者向けのヒント:スクリーンショットの下に編集可能なバージョンの図へのリンクを追加することを忘れないでください。そうすれば、後で必然的に状況が変わったときに簡単に更新できます。

数字を含める

多くの場合、問題の規模によって解決策が決まります。レビュー担当者が世界の状態を把握できるように、DB行の数、ユーザーエラーの数、待機時間などの実際の数値と、これらが使用量に応じてどのようにスケーリングするかを含めます。Big-O表記を覚えていますか?

面白くしてみてください

スペックは学術論文ではありません。また、人々は面白いものを読むのが好きなので、これは読者の関心を維持するための良い方法です。ただし、コアアイデアから離れるほどこれをやり過ぎないでください。

あなたが私のように面白くするのに苦労しているなら、ジョエル・スポルスキー(明らかに彼の喜劇の才能で知られています…)はこのヒントを持っています:

面白くする最も簡単な方法の1つは、それが求められていないときに具体的にすることです[…例:]「特別な関心」と言う代わりに、「左利きのアボカド農家」と言います。

やる懐疑テスト

設計ドキュメントを他の人に送信してレビューする前に、レビュー担当者になりすましてパスを取得してください。このデザインについて、どのような質問や疑問がありますか?次に、それらに先制的に対処します。

やるバケーションテストを

インターネットにアクセスできないまま長期休暇をとる場合、チームの誰かがドキュメントを読んで、意図したとおりに実装できますか?

設計ドキュメントの主な目標は知識の共有ではありませんが、他の人が実際に役立つフィードバックを提供できるように、これは明確さを評価するための良い方法です。

処理する

ああ、そうだ、恐ろしいP-word。設計ドキュメントは、間違ったソリューションまたは間違った問題のソリューションを実装するために多くの時間を無駄にする前に、フィードバックを得るのに役立ちます。良いフィードバックを得るための芸術はたくさんありますが、それは後の記事のためです。とりあえず、デザインドキュメントの書き方とフィードバックの入手方法について具体的に話しましょう。

まず第一に、プロジェクトに取り組むすべての人が設計プロセスの一部である必要があります。技術リーダーが多くの決定を後押しすることになっても問題ありませんが、全員が議論に参加し、設計に賛同する必要があります。したがって、この記事全体の「あなた」は、プロジェクトのすべての人を含む実際には複数形の「あなた」です。

第二に、設計プロセスは、ホワイトボードの理論化のアイデアを見つめることを意味するものではありません。手を汚して、潜在的な解決策のプロトタイプを作成してください。これは、設計ドキュメントを作成する前にプロジェクトの製品コードの作成を開始することと同じではありません。そうしないでください。しかし、アイデアを検証するために、ハッキーな使い捨てコードを自由に作成する必要があります。探索的コードのみを記述できるようにするには、このプロトタイプコードのいずれもmasterにマージされないようにするルールを作成します

その後、プロジェクトの進め方がわかり始めたら、次のようにします。

  1. チームの経験豊富なエンジニアまたは技術リーダーにレビュー担当者を依頼してください。理想的には、これは問題のエッジケースに精通している、および/または精通している人です。必要に応じてボバで賄賂を贈ります。
  2. ホワイトボードを持って会議室に入る。
  3. このエンジニアに取り組んでいる問題を説明してください(これは非常に重要なステップです。スキップしないでください!)。
  4. 次に、考えている実装について説明し、これが正しい構築であることを納得させます。

設計ドキュメントの作成を開始する前にこれらすべてを実行すると、より多くの時間を費やして特定のソリューションに執着する前に、できるだけ早くフィードバックを得ることができます。多くの場合、実装が同じままであっても、レビュー担当者は、カバーする必要のあるコーナーケースを指摘し、混乱の可能性のある領域を示し、後で遭遇する可能性のある問題を予測できます。

次に、デザインドキュメントの大まかなドラフトを作成したら、同じレビュー担当者にもう一度読んでもらい、デザインドキュメントの[タイトルと人]セクションにレビュー担当者として名前を追加して、ゴム印を付けます。これにより、レビュー担当者に追加のインセンティブと説明責任が生まれます。

その点については、設計の特定の側面について専門のレビュー担当者(SREやセキュリティエンジニアなど)を追加することを検討してください。

あなたとレビュー担当者がサインオフしたら、追加のフィードバックと知識の共有のために、設計ドキュメントをチームに送信してください。遅延が長引くのを避けるために、このフィードバック収集プロセスの期限を約1週間にすることをお勧めします。その週内に人々が残すすべての質問とコメントに対処することを約束します。コメントをぶら下げたままにする=悪いカルマ。

最後に、あなた、あなたのレビュアー、およびドキュメントを読んでいる他のエンジニアの間で多くの論争がある場合は、あなたのドキュメントのディスカッションセクションにすべての論点を統合することを強くお勧めします。次に、さまざまな関係者との会議を設定して、これらの不一致について直接話し合います。

ディスカッションスレッドの長さが5コメントを超える場合は常に、対面でのディスカッションに移行する方がはるかに効率的である傾向があります。全員が合意に達することができなくても、最終的な電話をかけるのはあなたの責任であることに注意してください。

最近ShreyBangaと話をしたところ、Quipにも同様のプロセスがあることがわかりました。ただし、チームのレビュー担当者として経験豊富なエンジニアまたは技術リーダーがいることに加えて、別のチームのエンジニアにドキュメントをレビューしてもらうことも提案されています。私はこれを試していませんが、これがさまざまな視点を持つ人々からのフィードバックを取得し、ドキュメントの一般的な読みやすさを向上させるのに役立つことは確かです。

上記のすべてを完了したら、実装を開始します。余分なブラウニーポイントについては、デザインを実装するときに、このデザインドキュメントを生きたドキュメントとして扱います。元のソリューションに変更を加えたり、スコープを更新したりすることにつながる何かを学習するたびに、ドキュメントを更新してください。すべての利害関係者に何度も何度も説明する必要がなくなったら、後で私に感謝します。

最後に、少しの間、本当にメタを取得しましょう。設計ドキュメントの成功をどのように評価しますか?

私の同僚のKentRakipは、これに対して良い答えを持っています。適切なROIの作業が行われれば、設計ドキュメントは成功します。つまり、設計ドキュメントが成功すると、実際には次のような結果になる可能性があります。

  1. 設計ドキュメントの作成に5日間を費やします。これにより、技術アーキテクチャのさまざまな部分について考える必要があります。
  2. X提案されたアーキテクチャの最もリスクの高い部分であるレビューアからフィードバックを受け取ります
  3. Xプロジェクトのリスクを軽減するために、最初に実装することにしました
  4. 3日後、それXは不可能であるか、当初の意図よりもはるかに困難であることがわかります。
  5. このプロジェクトでの作業を中止し、代わりに他の作業を優先することにしました

この記事の冒頭で、設計ドキュメントの目標は適切な作業が確実に行われるようにすることであると述べました上記の例では、この設計ドキュメントのおかげで、後でこのプロジェクトを中止するためだけに数か月を無駄にするのではなく、8日しか費やしていません。私にはかなり成功した結果のようです。

ご質問やご意見がございましたら、以下にコメントを残してください!また、チーム内でドキュメントを異なる方法で設計する方法についてもお聞きしたいと思います。

クレジットが必要なところでクレジットを与えて、私はPlaid(私たちは雇っています!私たちと一緒にいくつかの甘い技術システムを設計して構築してください)とQuoraで何人かの素晴らしいエンジニアと一緒に働いて上記の多くを学びました。

この投稿が気に入った場合は、Twitterでフォローして、エンジニアリング、プロセス、バックエンドシステムに関するその他の投稿をご覧ください。