いいデザインドックを作成するため、個人的にやっていること・やったこと

デザインドックを作成するときに注意するべき点をチェックシートとしてまとめています。

チェックシートは、推敲するときに使っていて、分かりづらくないか？漏れがないか？などをチェックしてます。

チェックシートの一部を抜粋すると以下のような感じですね。

[ ] 目的が書かれているか？
[ ] 専門用語の説明はしてあるか？
[ ] 章立てを行い読み手が必要な情報に辿り着けるようになっているか？
[ ] 全ての権限が考慮されているか？
[ ] 全てのデバイスを考慮しているか？

チェックシートを使って推敲すると、クオリティを一定に保つことができるので、個人的には効果がある取り組みだと思ってます。

デザインドックは、今後の開発方針をまとめて書くので、考えることが多く記述漏れなどが起こりやすいんですよね。

このチェックシート、最初は、自分用に会社の社内Wikiに書いていたのですが、他のメンバーにも好評で今では有効活用してくれているらしいです。結構嬉しい。

作成したデザインドックは、メンバーのレビューを通すようにしてます。

自分の考えている方針が間違ってないか？内容が分かりづらくないか？をチェックしてもらうためです。

以前は、チャットを使ってレビューのやりとりをしていたのですが、

などの問題が出てきたので、今は、MTGを設定して口頭でやるようにしてます。

デザインドックのレビューは、内容的に必ず議論が発生するので、明らかに口頭の方が早いと思ってます。

また、小さな疑問を拾いやすいので全員が納得した状態で開発が進むようになりますし、読み手が分かりづらいと感じた所も明確になりデザインドック自体のクオリティも改善できます。

ちなみに、今のチームでは、毎日３０分、レビュー専用の時間を確保していて、必要に応じてMTGを開催するというやり方をとっています。時間が確保されていると気軽にレビューをお願いできますし、全員が必ず集まることができるので便利。

誤字脱字や表記のブレがあるだけレビュワーに負荷がかかるので、TextLintを入れて自動校正できるようにしたかったのですが、これはうまく機能しなかったですね...

Notionを使ってデザインドックを書いているのですが、

というめんどくさい手順を踏む必要があり、結局使わなくなりました。

よしなにブラウザ上で自動校正するものがあればいいのですが、いまだに見つけられてないですね...

他にやったこととしては、

などがあったのですが、特にストーリーがないので省略しました。

ドキュメント作成能力は、エンジニアとして結構大事なスキルだと思うので日々高めていきたいですね。ちなみに自分は読んでないですが、👇この本は結構いいらしいです。いつか読む。

KASHIMURA Blog