ドキュメント管理

ドキュメント管理#

部署内のドキュメントの管理についてメモ

関係ありそうな学問分野#

関係ありそうなサービス#

管理のポイント#

ネット上の「こう管理してます」系のスライドによく出るポイントまとめ

CI/CDの活用（自動化）#

校正の自動化（Linter）など

ドキュメントの種類を分けて管理する#

フローとストックの分離#

ROIを考え、どのくらい保守するかガイドラインを設ける

文書の種類

  • ストック：半永久的（プロダクト・組織がなくなるまで）に蓄積すべき情報

    • 例：手順書、開発ガイドライン、実装TIPSなど

  • 準ストック：特定の期間（プロジェクト中など）に限り蓄積すべき情報

    • 例：仕様、Design Doc、ユーザーインタビュー

  • フロー：蓄積する必要がない情報

    • 例：議事録、作業ログなど

参考：

イミュータブルドキュメントモデル#

  1. 意思決定は不変な情報とする。

  2. 必要な場合に限り、可変な情報として仕様・設計を記録する。

参考：

（出所：更新”しない”ドキュメント管理 「イミュータブルドキュメントモデル」の実運用 - Speaker Deck）

差分管理#

Gitを用いることで、差分がわかりやすく、レビューしやすくする

階層整理型はスケールが難しい#

階層整理型のWikiは整理整頓を続けるための警察が必要

どういうドキュメントを書くか#

主に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 Notes

（出所：初めて書くPRD（プロダクト要求仕様書）｜Miz Kushida）

Design Doc#

ソフトウェアの設計についての文書。

  • どう実装するか

  • 誰がやるか

などを書く様子。

Design Doc の書き方 / How to Write a Design Doc (Ja ver.) - Speaker Deck

フォーマット例
背景、目的 (Why?)
検討した別の方法 (alternatives considered)
トレードオフ (Why not?: なぜ別の方法にしなかったのか？)
設計、アーキテクチャ (How?)
メンバー (担当者やレビュワー) (Who?)
セキュリティやプライバシーについての考察など
他プロジェクトとの関連性
テスト，モニタプランなど

基本的には、ソースコードを見てもわからない部分をDesign Docに書いて、議論するのが一般的のようです。

Googleなどで利用されているDesign Doc入門 - MyEnigma

Architectural Decision Record (ADR)#

日々の意思決定を記録するドキュメント。

「どうしてこの設計にしたのか」があとから参照しやすい。

フォーマットの例
# タイトル

# コンテキスト

# 内容

# ステータス
（下書き / 提案済み / 承認済み / 廃止 / 非推奨）

# 影響

日々の意思決定の積み重ねを記録するアーキテクチャ・デシジョン・レコード / Architectural Decision Records - Speaker Deck