shimo
エンジニアの中の人
「Design Doc」って何なのか?

全然意識はしてないのですが、

投稿する日付が見事に一か月ごとになっていてなんだかうれしい気持ちになりました。


そんなことはよくて今日は「Design Doc」について話そうかと思います。

いつもは結論から書くスタイルなのですが、Design Docっぽくシナリオ形式で書いていくことにします。

Design Docとの出会い

「いちいち英語で書いててうざい」と思った方、すいません。「デザインドック」と書くのが違和感しかなくて「Design Doc」で統一しています。うざくならなないように擬人化します。

僕が彼と出会ったのはメンロパークでした。 サンフランシスコとサンノゼの間くらいにあるちょっと田舎感あるいい街です。

メンロパークにはFacebookの本社があります。 そこに僕が訪ねた際にFacebookの社員の方に紹介してもらいました。

GoogleやFacebookでも彼は起用されているらしく、とても優秀

何かと問題が多い設計書

現場に入ってよくある話としては

  • 設計書とソースコードが乖離している
  • 設計書が読みにくい
  • そもそも設計書なんてものはない

が多い印象です。

設計書とソースコードが乖離している

一番多いケースなんじゃないかなと思います。

最初はやる気マックスで設計書頑張って作るんだけれども、だんだんその勢いも失速してきてある時の緊急対応からソースコードだけ更新されていくという。。。

設計書が読みにくい

書式が統一されてなかったり、そもそも拡張子が違うなんてことも?

追加要件もどこから飛んでくるかわからず、Slackなのかメールなのかはたまた口頭なのか。

そもそも設計書なんてものはない

これも多いパターンです。 やる気も出ず、設計書がないという。

一時期は「ソースコードが設計書」だから設計書なくていいんじゃね?と思っていた僕ですが、

今では頭を冷やしてやっぱり設計書は必要という結論に至っています。

なにかと開発者以外の方も見ますからね。


つまり、設計書を作り運用するのは難しいわけです。

そこで彼が登場するわけですね。

Design Docとは何者か?

設計書はエクセルとかスプレッドシートで書くところが多いかと思いますが、Design DocはDocなだけにドキュメントで書くそうです。

僕が彼と出会った場所、シリコンバレーで広く使われているそうで日本にはあまりなじまず普及が苦戦している模様。

基本的なポリシーとしては「コードにかけないことを書く」ということでコード読んだらわかるでしょみたいなことはドキュメントには書かず、What、How、Whyのような観点で書いていきます。

要は細かいことは書くなってことですね。

GoogleさんがDesign Docを公開してくれているそうなので貼っておきます。(有難し)

WebKit WebSocketDesign Doc(グーグル)

The Chromium Projects - Extensions

Dagger 2.0

Design Docどうやって書くの?

参考は貼りましたが、とはいってもどう書くの?という疑問は消えないわけでこちらにつづっていきます。

1. 要件を整理する

やっぱり要件を把握していないとかけないのでお客さんとミーティングするなり、自身で考えるなりで要件を一つ一つ洗い出していきます。

2. Design Docにタイトルをつける

先ほどのGoogleさんのドキュメントにもあったようにタイトルを付けます。シンプルなものがよいかと思います。じゃないとタイトルだけで見てもらえなかったりするので。

あと自分も書いた後忘れるんでね。これ何のファイルだっけ?ってなったらソースコードとドキュメントの間に溝が生まれ始めます。

3. ゴールや背景を書く

タイトルを書いたら続いて結論。

そのほうがシンプルでわかりやすいです。

小説だったらまったく面白くない話になりそうですが、ここではわかりやすさを優先しましょう。

またなんでこのプロダクト作ってるんだっけ?とならないように作るまでの経緯だったり、背景を書いておきましょう。

また今後開発に参加してくれる人も読めるので、設計に関して深い理解が得られます。

4. 大まかな設計、プロダクト概要を書く

ここにはコードを見ただけではわからないようなもの、例えばアーキテクチャ、システム構成図、クラス図などを記述したりします。

絵がいっぱい書いてあったほうが楽しいですね!!

5. セキュリティやプライバシーについての考察を書く

問題とその対処法をセットで書いておくとわかりやすいです。いざというときに手順があるのは安心です。

6. 各機能の設計を書く

すこし細かいことですが、ソースコードと同じ内容にならないように気を付けながら機能の目的、アルゴリズム、データ構造、インタフェースを記述します。

  • いつ提案されたか
  • 担当者
  • 担当チーム
  • 機能概要
  • ユースケース
  • FAQ

みたいな流れで書いてました。

もちろんAPIならSwaggerの内容もここに記載するようなイメージですね。

Design Docを書くなら?

やはりGoogleドキュメントかなと思います。

アウトラインが自動で生成されるし、目次も作れるし、バージョン管理もできます。

唯一のデメリットとして忘れ去られると更新されなくなるということでできればソースコードに近い場所に置いておきたいんですよね。

そうなるとマークダウンとかで書いてGitHubとかで管理したほうがいいんでしょうけど、目次書くのだるすぎる。

天下のGoogleではGoogleドキュメント使ってるのでいまのところそれを使うのがよさそうです。

「今もなお未完成である」

Design Docを書くにあたって一番大切なことだと思います。

常にアップデートされ続けるものとして、参加するすべてのメンバーが認識し、理解すること。

そうすることで設計書が腐ることはないのかなと思います。

僕自身のDesign Docに関しての理解もまだまだですが、もっとわかりやすく伝えられるように努力します。

参考


Last modified on 2019-12-13