【ドキュメント】仕様・設計に関する資料を作成する - Githubissues

shusuke0812 / KikurageApp-iOS

🚀 Dev - Kikurage Cultivation App（Recording、Monitoring of temperature and humidity）

MIT License

6 stars 1 forks source link

【ドキュメント】仕様・設計に関する資料を作成する #90

Open shusuke0812 opened 2 years ago

shusuke0812 commented 2 years ago

内容

アプリの仕様・設計についてまとめたドキュメントを作成する
目的
- 第３者（もしくは未来の自分）がコードを見て編集する際の手助けとなること（仮）
- ドキュメントを作成する過程で仕様の全体像を把握し課題を整理すること（仮）

TODO

[x] 目的の再整理（誰の、何のための）
[ ] 仕様書の種別を整理する（開発環境構築、スクリーンの全体像・導線、各スクリーンの仕様、WebAPI、DB、セキュリティ、コード設計....blah blah）
[ ] 仕様書のフォーマットを作成する
[ ] 仕様書のテンプレートファイルを作成する（Markdown or GitBook、編集のしやすさ・閲覧のしやすさを考慮）
[ ] 仕様書を作成する
[ ] 仕様書の英語化（want）

参考

Developerサイトの開発者向けドキュメントを参考にすると良いかも
- LINE Developer ドキュメント
API Doc制作ツール（Redoc）

shusuke0812 commented 2 years ago

クラス図はこちらに追加中 https://github.com/shusuke0812/KikurageApp-iOS/tree/develop/Docs/class_diagram

参考

shusuke0812 commented 1 year ago

こちらの講演が参考になった✨

Youtube - システムの陳腐化が減価償却の速度を追い越した時代に生きる僕たち・私たち

ドキュメントを作る論点
- システムを継続的に改善していくためにはどのようなドキュメントが必要か
ドキュメント項目（赤文字が特に大事）

スクリーンショット 2022-12-08 21 32 14

なぜシステムを継続的に改善する必要があるのか？、どのようにシステムを改善していくべきか？の詳細は上記動画を参照
一部抜粋すると「システムを改善するにあたりそのシステムのアーキテクチャや構造を理解していることが前提条件としてあり、その知識の補完としてデザインドキュメントが必要」と説いている（あくまでデザインドキュメントの制作は一例）

なぜ良いと思ったか？

改善の適切なアプローチを最適パスで発見するために必要だという観点に共感したため
コードを読んだだけでは理解できないことに遭遇した経験が少なからずあり、また同じような声もチームメンバーから上がったことがあるため「なぜそのようなシステム構成にしようと思ったのか、なぜ別の構成にしなかったのか」を言語化しておくことはシステムの改善活動に必要だと痛感したため

これらを踏まえてどのようなドキュメントを準備すべきか

まずは、コード・コードコメント・コミットメッセージ・仕様書等から読み取れないシステムあるいはアプリの設計理由を整理していく
検討したが選定しなかった設計とその理由も追記する
その時に選定した設計の理由をうまく言語化できない場合は、その旨あるいは参考にした記事のURLを貼っておく（時間の経過とともに知識が増え、後になって解決できる可能性があるため）

まとめ

誰のため：チームのため（今いるメンバー、後から来るメンバー）
何のため：システムを継続的に改善していく時に改善の適切なアプローチを最適パスで見つけるため
何を書く：システムの設計理由、他に検討したが採用しなかった設計理由（全体像がみえること。局所的な細かい部分についてはコード、コードコメントなどに落とし込むこと。）