DesignDocとminispecの書き方お悩み所

お悩みの記録

ここでは個人開発をしている時に悩んだ内容を備忘録的に残していきます。
今回記載するのはDesignDocとminispecを書いて悩んだ話になります。
Design Docは元々googleで作られていたどのような機能を作成するかをまとめた開発資料です。
minispecは主にstartupで利用される資料で、作成したい機能はどの様な理由や経緯で提案されているのかを示すものです。

対象者

開発用の文章を書く機会が少ない方
仕様を考える時どのように考えているのか知りたい方
これから複数名の人と開発を行う方

解決の為の結論

• 書き出す前にスタートからゴールまでの構想を作成する

• スタートとゴールをイメージしたら、章ごとに関心事で分割する

• 勘違いしやすい部分や複雑な内容については特に細かく記載する

経緯

そもそもなぜDesignDocやminispecを書く必要があるのか

ここは様々な理由があると思うのですが、私としては以下の様な理由があります

1.   個人開発といえども関係者がいるので、何故その機能を作成するのか理由が無いといけない

2. 文章を作成することで自分の中で完結するものではなくなり、他の人のレビューを受けやすくなる。

3. なんでこの機能作るのか後で見返しても理解ができる

悩み所はどこだったのか

実際に書いてみて悩んだのは以下の点になります

• そもそも具体的な書き方をよく分かっていない

• どこまで詳細に記載すればいいのか勘所が分からない

• 自分では分かっているつもりの部分でも文書化した結果うまく説明することができない

上記の様な理由がありました。
その中でも特にすぐ改善できそうな上位二つについては、社内のPdMやエンジニアに聞いて、おおよその疑問点を解決することができました。

お悩み解消ポイント

文章を書く際には、まずスタートからゴールまでを決めるベし

いきなり文章を書こうとすると迷うものです。
例えばminispecを初めて書いた時の私で言うと、なぜこの機能を作りたいのか理由があると思うのですが、それをひたすら記載してしまい。全体として何がポイントになるのか、ユーザーの課題は何？とか何故この機能を作ると嬉しいのか？のような記載が抜けてしまい動機の部分が薄くなってしまいました。
この様な事態を回避する為にも事前に予め章立てをしておくことは重要です

特に見てほしい部分や勘違いしやすい部分は記載を厚くすべし

他者に見てもらい気づくことは多々あると思います。
私は文章をかなり自己完結させてしまう節があり他者の人が見たときに、ぜコレで問題ないのか理解できないという事がありました。
今となれば事前に明記しておけばこの様なことは回避できたかなと思います。
例えばなのですが、minispecにはユーザー情報を削除できると記載していたのですが、レビュアーはユーザー自身が自分のユーザー情報を削除できる事を許容するのかと言う鋭い指摘をもらいました。当時は自分の中でユーザー情報についてのbackendとfrontendの疎通の実装を早めたいが為に記載していなかったのですが、今思えばスコープアウトとして自分のユーザー情報を削除できることは許容すると記載すれば終わる話でした。

コレから

書き方や構想の仕方はわかったものの何処まで記載するかや、何処までの内容をカバーするのかは今の自分では分かっていないので経験値を増やす為にも色々開発文章を作成しながら経験値を増やしていこうと思います。
あとは図解化

指摘を受けてhandler内の分岐を図解化