最近(?) のドキュメンテーション関連手法のまとめ¶
システム開発の過程に行われるドキュメンテーションやその関連の手法について、最近目についたものをメモした。単なるインデックスなので詳細は触れない。 1
Working Backwards¶
参考
(メモ)
Working Backwards では、先にプレスリリース・FAQ やユーザマニュアルを作ってから企画審査を行う。ゴールを決めてからスタートを切りましょうという話。
FAQ やユーザマニュアルまで作成となると、企画段階でほぼ仕様が固まってないとできない。どこまで厳密なものが求められているのか不明だが、個人的には開発途中で仕様が右往左往するのを避けるという目的もあると解釈しているので、かなり確度の高いものを作るのではないかと思う。
Design Documents¶
参考
(メモ)
要は単に「設計書」なのではないかと思うのだが、伝統的なシステム開発での設計書に対して比較的カジュアルであり、必要最低限しか書かない、という点で区別されているらしい。また設計上の決定においてなぜそのように決定したか、何を判断材料としたかに重点が置かれるとのこと。
Architectural Decision Records¶
参考
(メモ)
アーキテクチャ上の決定を１文書として残す。後から見たい、あるいはコードには記録されない情報は WHY （:なぜそうしたか、他にどんな案が検討されたか、なぜ別の案を採用しなかったか）の意思決定の部分であり、それをそのまま１つの文書単位にするのはシンプルでわかりやすいように思う。
RFCプロセス¶
参考
(メモ)
OSS の機能追加を含む意思決定において、初めに RFC (Request for Comment) を作成しコミュニティで議論したのちコアメンバーの会議などで採用可否を検討する。
ARCHITECTURE.md¶
参考
(メモ)
1ファイル（でおさまる量感で）アーキテクチャーの概要などを書く
総合コメント¶
個人的な解釈では、それぞれの課題意識は以下に挙げたものなのではないかと思う。
ゴールが不明で開発がスムーズにいかない > 明確なゴールを設定する
コードから Why が読み取れない > 運用後に困るので「なぜそれを選んだか」記録を残す
採用しなかった案とその理由が記録されない > あとで方針を変える時などに困るので記録する
プロジェクトに主体的に参加してほしい > 意思決定部分もなるべく公開してやる
プロジェクトに参加しやすくしたい > 概要などを整備する
ドキュメンテーションは「書きすぎ」「更新の手間」がマイナス要素として語られることがあるが、上述した手法のように開発プロセスにドキュメンテーションを組み込むようにすればマイナス面は抑えられるのではないかと思う（ADR や RFC プロセスでは必然的に文章が必要となるし、マニュアルはどのみち最新の状態を保つ必要がある）。
Footnotes
- 1
最近知ったというだけで調べてみると昔から公開されていた話が多い
最近(?) のドキュメンテーション関連手法のまとめ — ykrods note
https://www.ykrods.net/posts/2021/10/08/documentation-methods-2021/