はじめに
メーカーのコーポレート部門でエンジニア兼スクラムマスターをやっているモンゴルです。
の続きを書いていこうと思います。
前回は次のことを書きました。
- ドキュメントを作ることで対話が生まれ共通認識を作ることは大事ということ
- 環境によって整備できていない現場、整備されていなくても成立している現場があったこと
今回はアジャイル開発においてどういうドキュメントが必要なのか？どうやってメンテナンスしていくか？ということを書いていこうと思います。
TL;DR
- イテレーティブにソフトウェア開発をしていくときに重要なのは認知負荷の低さ
- CIで統一感を作り、認知負荷の低さを保持していく
- 自動化できないところをドキュメントを使用しながら認知負荷を下げていく
- 継続的にメンテナンスしていく仕組み作りも考える
- その時点で共通認識を作るための、ドキュメントも重要
- その時点でしか使われないと割り切って作っていく
ソフトウェアを作るにあたって大事なこと
継続して開発されるソフトウェアを開発するうえで大事なのは、認知負荷が低いソフトウェアにし続けることだと考えています。
アジャイルな開発では、検証、実験、ということで今まで考えていない仕様が追加されることがあります。
また、プロジェクトが続けば人の入れ替わりもあると思います。
ここで重要なのが認知負荷の増加を抑えるかです。
カオスに向かっていく、ソフトウェア開発の中で認知負荷の増加を抑えるためには、次のような要素があると考えています。
- 一般的な概念、思想を取り入れて設計されていること
- 新しく入ってきたメンバーも、既知であったり、知らなかったとしても学習資材があるので学習コストが低くなります
- 設計やコードに統一感があること
- コアなメンテナがいて、その人がリーダーシップを発揮することが重要だと考えています
ただし、上記を実践しようとしたときに、ドキュメントを作り、人がレビューで指摘しながら、認知負荷を低く保っていくことになりますが、限界があります。
そのために必要なのがCIです。
CIで認知負荷を低くする
テストを書く
テストは期待する挙動が書かれているので、仕様書となりえます。
これによって、何が想定された挙動なのか把握できるため、認知負荷増加を抑えます。
というか、想定された挙動が分からないと、一からコードを読んだり、関係者に聞く、実際に動かして確かめるなどが必要であるため、認知負荷が爆増します。
GitHub Actionsで色々仕込む
Linterでチェックして、統一感のあるコードを書くのが重要です。場合によってはコードの依存関係をチェックする自作のツールを作るといいでしょう。
適応度関数を導入し、そのソフトウェアで重要な指標を定め、それを定期的に計測していくことも重要です。
「適応度関数とは？」という方は次の書籍がおすすめです。
また、設計書の類、例えばER図の生成も可能だと思います。
自動化の前提となるところ、自動化できないところをドキュメントを使用しながら認知負荷を下げていく
自動化にも限界があると思います。そういう箇所について、ドキュメントを作っていくといいと思っています。
ただし、継続的にメンテナンスされるドキュメントを作っていくために、メンテナンスすべきドキュメントとしないドキュメントを分けることが重要だと思っています。
次の記事のように、継続的に仕分けをするプロセスなどを検討するといいと思います。
ドキュメントで共通認識を作る
上記は運用ルールやアーキテクチャ図など、現時点でのHowやWhatを説明するイメージで書いていましたが、人に説明するために、複数のHowを整理したり、過去のWhyを残しておいて共通認識を作ることも重要だと思っています。
例えばADRです。
意思決定は後から追いづらく、「何故かこうなっている」ということになりがちなので、方針だけでなくその経緯も見られるようにしておくと良いでしょう。
また、前回記事にも書きましたがドキュメントを作るだけでなく、それをもとに会話するというのが重要だと考えています。
その時点でしか使われないかもしれませんが、会話が起きれば目的達成だと私は思うようにしています。
メンテナンスされないことは悲しいですが、ポジティブにとらえて割り切って作っていくのもありだと思います。
おわりに
偉そうに書きましたが、あくまで私はこう考えるという話です。
皆さんの置かれている状況によっても、「どういう点に気をつける必要があるか？」という点は変わってくると思います。
皆さんが、持続可能なドキュメント管理を考えるときの一つの参考になれば幸いです。
