documentation
概要
よいドキュメント(技術文書)があると、後から見てもスムーズに入っていきやすいので重要である。ドキュメントの最大の利点は非同期性で、プログラマーにとって重要に見える。何回も同じ説明をしたくない。他人だけでなくて未来の自分すら理解していたことを忘れるので、いつでも把握しやすいのは思い出すコストや敷居を下げることになる。
効果的なドキュメントについてまとめる。一般的なコミュニケーションについてはcommunicationへ。
Memo
機能開発後の普及方法まで考慮する
たとえば管理画面に2段階認証機能を追加した場合を考える。この場合、機能を追加するのは当然なのだが、「使える」だけでは不十分である。機能追加の意味は2段階認証を設定して使ってもらうことなので、普及まで考えなければならない。
- 数値としてどれくらい設定されたかを把握する方法を確保する。メトリクスとして設定する
- ユーザ自身が設定状態を確認する方法を確保する。設定してないときはアラートを出すとよい
- 管理者が設定状態を確認する方法を確保する。一覧で表示できるとよい
- 使用方法のチュートリアルを整備する。たとえば2段階認証後に自動ログアウトすることで使い方が理解できる
- 読みやすいヘルプドキュメントを整備する。どこまでが任意なのかを書くとすっきりする
- 定期的に未設定者をリマインドする習慣や、仕組みを整備する
- 未設定者を頻繁にアナウンスし、移行をうながす
ポストモーテム(事後分析)
根本的原因を分析し、自分の失敗をドキュメント化する。
- 分析対象イベントの簡潔な要約
- 発見から調査を経て解決に至るまでの分析対象イベントのタイムライン
- 分析対象イベントの主要原因
- 影響と損害の評価
- 問題を直ちに修正するための一連アクションアイテム(要処理事項)とそのオーナー
- 分析対象イベントが再度発生するのを防ぐための一連のアクションアイテム
- 学んだ教訓
Reference
はじめに - AI Native Development Guide
AIネイティブ開発ガイド。AIと協働しやすいように整備する。
Fine Software Writings
ソフトウェア開発に関する文章の翻訳。
Web 関連仕様 日本語訳
仕様の日本語訳。
Handbook | GitLab
最強の文書化企業の成果物。