部署内のドキュメントの管理についてメモ
関係ありそうな学問分野¶
ナレッジ・マネジメント （経営学の研究分野。野中郁次郎が創始？）
管理工学
関係ありそうなサービス¶
AIドキュメントリバース（SHIFT）：ソースコード → ドキュメント に変換するツールらしい
ナレッジワーク：ドキュメントの検索の快適性を重視したドキュメント管理システム
管理のポイント¶
ネット上の「こう管理してます」系のスライドによく出るポイントまとめ
ドキュメントの種類を分けて管理する¶
フローとストックの分離¶
ROIを考え、どのくらい保守するかガイドラインを設ける
文書の種類
ストック：半永久的（プロダクト・組織がなくなるまで）に蓄積すべき情報
例：手順書、開発ガイドライン、実装TIPSなど
準ストック：特定の期間（プロジェクト中など）に限り蓄積すべき情報
例：仕様、Design Doc、ユーザーインタビュー
フロー：蓄積する必要がない情報
例：議事録、作業ログなど
参考：
差分管理¶
Gitを用いることで、差分がわかりやすく、レビューしやすくする
どういうドキュメントを書くか¶
主にITエンジニア目線でのドキュメント
Product Requirements Document¶
プロダクトの仕様を記載したドキュメント
PRDのフォーマット例
1. Intro & Goal
2. Concept / Value Proposition
3. Product Vision
4. Who's it for? ｜誰のためにあるか
5. Why build it?｜なぜ創るか
6. What is it?｜どういうものか
6–1. Glossary｜用語
6–2. User Types
6–3. UI/Screens/Functionalities｜UI/画面/機能
7. Brainstormed Ideas｜その他アイデア
8. Competitors & Product Inspiration｜競合
9. Seeding Users & Content｜初期ユーザーと獲得戦略
10. Mockups
11. Tech NotesDesign Doc¶
ソフトウェアの設計についての文書。
どう実装するか
誰がやるか
などを書く様子。
Design Doc の書き方 / How to Write a Design Doc (Ja ver.) - Speaker Deck
フォーマット例
背景、目的 (Why?)
検討した別の方法 (alternatives considered)
トレードオフ (Why not?: なぜ別の方法にしなかったのか？)
設計、アーキテクチャ (How?)
メンバー (担当者やレビュワー) (Who?)
セキュリティやプライバシーについての考察など
他プロジェクトとの関連性
テスト，モニタプランなど基本的には、ソースコードを見てもわからない部分をDesign Docに書いて、議論するのが一般的のようです。
Architectural Decision Record (ADR)¶
日々の意思決定を記録するドキュメント。
「どうしてこの設計にしたのか」があとから参照しやすい。
フォーマットの例
# タイトル
# コンテキスト
# 内容
# ステータス
（下書き / 提案済み / 承認済み / 廃止 / 非推奨）
# 影響
日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード / Architectural Decision Records - Speaker Deck