ドキュメントに時間を掛ける
概要
- シックスワンにおけるドキュメントの整備はとても、とても大事だと思っています。
- 様々なスキルレベルのメンバーが、間隔をあけて日替わりで、プロジェクトを進行する難易度はとても高く、実際のところコーディング時間よりも、理解するためにコードを読む時間のほうが長いくらいです。
- まただれかが時間をかけて一生懸命コードを読み理解したとしても、次の日にまた別の人が同じようなコストをかけて、一生懸命読まないといけません。
- 理解するために必要な労力が100だったものを、10に減らすことができれば、それは継続して後から作業する人のコストを減らすことができます。
- それを実現するものが、コードにおけるドキュメント整備であり、そのための時間を掛けてもドキュメントを整備したいと思っています。
ドキュメントの種類
私は対象としているドキュメントは以下のものです
githubのRead.me
- プロジェクトの最初のドキュメントですが、これが最初の道しるべになります。
- ここに必要なものが全てそろっていることが理想です
コード内のコメント
- コード自体の精度も大事ですが、それと同じくらいコメントも大事です。
- これがあれば、コーディング時の理解も高まります。
仕様書
- データベースの設計など、これはどのような仕様で書かれているのか、といった仕様書です。
- 大袈裟なものではなく、こういう意図で記載しているというものでも構いません。
テストコード
- テストコードはそのコードが何を目的として、何を得ようとしているのかが一番わかる内容です。
- できる限りテストコードの作成をしていきたいです。
今後
- ルール整備
- これから皆さんで守っていくドキュメントの書き方を決めたいと表います。
- ドキュメント作成の徹底
- 今後はドキュメント作成を必ず行っていきたいです。
- Lintツール等の力を借りつつ、徹底をしていきましょう
- 省力化
- 手間を掛けてもドキュメント整備を行いますが、一方で省力化できるものはしていきたいです。
- GPT等の力を借りることも含めて、簡単に作れるように工夫をしていきましょう。