目的
分散したチームは、プレイブック、決定、および教訓が予測可能な方法で書き留められている場合、より迅速に動きます。このハンドブックは、オンボーディングがスムーズに進み、コンテキストがDMに閉じ込められることがなく、事後分析を将来のガードレールとして再利用できるように、知識をどのように収集するかを概説しています。
執筆の原則
- 明確さを第一に。 新しいチームメイトが一度通読して理解できる言語を目指します。明確化する脚注や用語集のエントリを追加して、専門用語を分解します。
- 速度よりも正確さ。 データ、リンク、および所有者を確認します。間違った構成スニペットは、更新が遅れるよりも多くの時間を無駄にします。
- 簡潔な構造。 段落を短くし、箇条書きを優先し、重要な警告やヒントにはコールアウトを使用します。
- 対象読者を意識する。 対象となる役割に合わせてドキュメントを調整します。ファシリテーターガイドでは、ツール、タイミング、および障害モードを強調し、ランブックでは、コマンドとロールバック手順を表面化させる必要があります。
- バージョン管理と所有者。 すべてのページには、「更新日」と、それを維持する責任者である所有者が記載されています。
ドキュメントのライフサイクル
ドキュメントを、SDLCをシャドウイングする継続的なループとして扱います。軽量のドキュメント開発ライフサイクル（DDLC）は、コンテンツを最新の状態に保ちます。
graph TD
A[計画] --> B(分析)
B --> C{コンテンツ開発}
C --> D[レビューと編集]
D --> E(公開)
E --> F[メンテナンスと更新]
F --> A
- 計画： 範囲、対象読者、および公開チャネルを定義します。ドキュメントを測定可能な結果と組み合わせます（例：オンボーディング時間の短縮）。
- 分析： 主題の専門家にインタビューし、指標を確認し、スクリーンショットまたはデータのエクスポートを収集します。
- コンテンツ開発： 共有テンプレートを使用してドキュメントを下書きします。フローの明確さが重要な場合は、Mermaidで図を埋め込みます。
- レビューと編集： 正確さとトーンについて、少なくとも1人の同僚と1人の責任ある所有者を通じてドラフトを回覧します。
- 公開： 共有ドキュメントサイト経由で公開し、検索およびサイドバーナビゲーションで表示されるようにページにタグを付けます。
- メンテナンス： 四半期ごとのレビューをスケジュールします。知識のずれを防ぐために、古いページをアーカイブまたはマージします。
私たちのスタックのツール
- Markdown優先のオーサリング： VS Codeまたはドキュメントポータルで記述し、書式設定をシンプルで差分がわかりやすいように保ちます。
- 静的公開： Astro + Starlightは、組み込みのナビゲーションを備えた、高速で検索可能なページをレンダリングします。
- 図表作成： アーキテクチャ、ワークフロー、およびデシジョンツリーにはMermaidを優先し、更新がバージョン管理下に留まるようにします。
- バージョン管理： すべてのドキュメントは、使い慣れたレビューワークフローを再利用するために、Gitのコードの横に置かれます。
展開
- チームのオンボーディングおよびスプリントのレトロスペクティブ中にハンドブックを紹介します。
- 標準を、ランブック、決定、およびインシデントレビューのテンプレートと組み合わせます。
- 「コンテキストまでの時間」（チームメイトが立ち上がるのにかかる時間）を追跡し、摩擦が生じたときにハンドブックを更新します。
- ドキュメント作業が機能の出荷と並行して評価されるように、貢献を公に称賛します。