LESSON 30分

ストーリー

あなた
新しく入った鈴木さんに開発環境のセットアップを教えたんですが、2時間もかかりました。先月も同じことを別の人に教えたのに…
あ
高
高橋アーキテクト
そのセットアップ手順は、どこかに書いてあるか？
あなた
えっと…Slackの過去ログにあるはずですが、探すのが大変で結局口頭で…
あ
高
高橋アーキテクト
それが”ドキュメントがない”ことのコストだ。同じ説明を何度も繰り返し、毎回2時間を失う。10人にやったら20時間だ。1回ドキュメントを書けば、あとは読むだけで済む。テクニカルリードの仕事は、チームのドキュメンテーション文化を作ることだ

ドキュメントの種類と目的

interface DocumentType {
  name: string;
  purpose: string;
  audience: string;
  updateFrequency: string;
  location: string;
}

const documentTypes: DocumentType[] = [
  {
    name: "オンボーディングガイド",
    purpose: "新メンバーの立ち上げを高速化",
    audience: "新入メンバー",
    updateFrequency: "入社のたびにフィードバックを反映",
    location: "リポジトリ docs/onboarding/",
  },
  {
    name: "ADR（Architecture Decision Record）",
    purpose: "設計判断の記録",
    audience: "開発チーム全体",
    updateFrequency: "意思決定のたびに追加",
    location: "リポジトリ docs/adr/",
  },
  {
    name: "Runbook（運用手順書）",
    purpose: "障害対応の手順を標準化",
    audience: "オンコール担当者",
    updateFrequency: "障害対応後に更新",
    location: "リポジトリ docs/runbook/",
  },
  {
    name: "API ドキュメント",
    purpose: "APIの仕様と使い方を共有",
    audience: "API利用者（社内/社外）",
    updateFrequency: "APIの変更と同時",
    location: "OpenAPI Spec + 自動生成",
  },
  {
    name: "技術仕様書（Design Doc）",
    purpose: "設計の全体像と意図を伝える",
    audience: "開発チーム",
    updateFrequency: "実装中に随時更新",
    location: "リポジトリ docs/design/",
  },
  {
    name: "チーム Wiki",
    purpose: "暗黙知の形式知化",
    audience: "チーム全体",
    updateFrequency: "随時",
    location: "Notion / Confluence / GitHub Wiki",
  },
];

ドキュメントを書いてもらう仕組み

「ドキュメントを書こう」と言うだけでは書いてもらえません。仕組みが必要です。

## 1. DoD（Definition of Done）に含める
タスクの完了条件にドキュメント更新を含める。
「コードを書いただけでは"Done"ではない」

## 2. テンプレートを用意する
空白のドキュメントに書き始めるのは難しい。
テンプレートがあれば、穴埋めで書ける。

## 3. コードの近くに置く
READMEやdocs/ディレクトリなど、コードと同じリポジトリで管理。
PRのレビュー対象にドキュメントも含める。

## 4. 自動生成を活用する
- APIドキュメント: OpenAPI Spec + Swagger UI
- コードドキュメント: TypeDoc / JSDoc
- 変更履歴: CHANGELOG の自動生成

## 5. 書いた人を称える
「このRunbook、助かりました」のフィードバックが次のモチベーション。

ドキュメントの品質を保つ

問題対策
古くなった情報が残る定期レビュー（四半期に1回）
どこに何があるか分からないINDEXページの整備、検索の改善
書いたが読まれないオンボーディングで読む機会を作る
情報が重複するSingle Source of Truth を決める
粒度がバラバラテンプレートとガイドラインの整備
## ドキュメントヘルスチェック（四半期に1回）

### チェック項目
- [ ] オンボーディングガイドで実際にセットアップできるか
- [ ] Runbookの手順は最新のインフラに対応しているか
- [ ] ADRの一覧は最新か
- [ ] リンク切れがないか
- [ ] 不要になったドキュメントはアーカイブされているか

Docs as Code

ドキュメントもコードと同様に管理する考え方です。

## Docs as Code の原則

1. **バージョン管理**: Git でドキュメントを管理
2. **レビュー**: PRでドキュメントもレビュー対象に
3. **自動化**: CI/CDでドキュメントをビルド・デプロイ
4. **テスト**: リンク切れチェック、スペルチェック
5. **プレーンテキスト**: Markdown / AsciiDoc を使用

## ツールの例
| ツール | 用途 |
|--------|------|
| MkDocs | Markdown → 静的サイト |
| Docusaurus | React ベースのドキュメントサイト |
| Storybook | UIコンポーネントのドキュメント |
| Swagger UI | OpenAPI からAPI ドキュメント生成 |

まとめ

ポイント内容
ドキュメントの種類オンボーディング、ADR、Runbook、API Doc等
書いてもらう仕組みDoDに含める、テンプレート、コードの近くに
品質維持定期レビュー、Single Source of Truth
Docs as CodeGit管理、PRレビュー、自動化

チェックリスト

  • チームに必要なドキュメントの種類を把握した
  • ドキュメントを書いてもらう仕組みを理解した
  • 品質維持の方法を学んだ
  • Docs as Codeの原則を確認した

次のステップへ

次は「技術ブログとナレッジ共有」を学びます。チーム内だけでなく、社外にも技術を発信する方法を学びましょう。

推定読了時間: 30分