【設計シリーズ:12】 運用マニュアル "生きた"ドキュメントを実現する構成図

概要

システムの安定稼働に不可欠な運用マニュアルは、なぜ更新されず形骸化するのか？本レポートは、ドキュメントをコードで管理する『Docs as Code』のアプローチでこの課題を解決します。テキストから作図できるMermaidを使い、障害対応フローやシステム構成図など、現場で即戦力となる5つの構成図サンプルをコード付きで詳説。

バージョン管理が容易で、常に最新の"生きたドキュメント"作成を可能にします。さらに、チームでの共同編集やレビューを円滑にする作図ツールCacooも紹介し、両者を組み合わせたハイブリッドなドキュメント運用術を提案します。

序章: なぜ今、あなたの運用マニュアルは「死んでいる」のか？

システムの安定稼働を支える生命線、それが「運用マニュアル」です。しかし、多くの現場でこのマニュアルが形骸化し、"死んだドキュメント"と化している現実があります。一度は詳細に作られたはずのマニュアルが、なぜ活用されなくなるのでしょうか。

理由は明白です。

• 更新の煩雑さ: WordやExcel、PowerPointで作成された図は、少しの変更でもレイアウトが崩れ、更新作業が億劫になります。結果、システムの変更にドキュメントが追随できず、情報が陳腐化します。
• 属人化とブラックボックス化: 更新が面倒なため、最新情報は担当者の頭の中にしか存在しなくなり、その人がいなければ誰も対応できない「属人化」が進みます。
• バージョン管理の困難: 「最新版は誰のPCに？」「あの変更は反映されている？」といったファイル管理の問題が頻発し、どの情報を信じてよいか分からなくなります。

こうした問題を解決し、運用マニュアルを常に最新で信頼できる "生きたドキュメント" へと蘇らせるアプローチが Docs as Code です。これは、ドキュメントをソースコードと同じように扱い、テキストベースで記述し、Gitなどのバージョン管理システムで管理する考え方です。

この Docs as Code を実現する強力なツールが Mermaid です。Mermaidは、シンプルなテキスト記述でフローチャートやシーケンス図などの作図を可能にします。テキストなので差分確認が容易で、レビューも簡単。Markdownファイルに直接埋め込めるため、ドキュメントと図を一体で管理できます。

本稿では、【設計シリーズ】第12弾として、このMermaidを活用し、「ク運用マニュアル」（クラウドサービスやプロダクトの運用マニュアル）に最適な構成図を作成するアイデアを、具体的なコード例と共に5つ紹介します。特に、プロセスの流れを表現しやすいdirection LR（左から右へ描画）の指定を基本とします。

さらに、記事の最後では、Mermaidの利便性を享受しつつも、より複雑な図の作成やチームでの共同作業を円滑に進めたいと考える方々のために、ビジュアルコラボレーションツール Cacoo がどのようにその体験を向上させるか、ほんの少しだけご紹介します。

第1章: 優れた運用マニュアルが備えるべき8つの構成要素

Mermaidで図を作成する前に、まず「優れた運用マニュアル」が何を網羅すべきかを定義する必要があります。以下の8つの要素は、インシデント発生時に迅速かつ的確な対応を可能にし、日々の運用をスムーズにするための根幹となります。

システム概要・アーキテクチャ

• 目的: 誰が読んでも、対象システムの全体像とコンポーネント間の関連性を理解できるようにするため。特に、新メンバーのオンボーディングや、普段そのシステムを触らないメンバーがインシデント対応する際に不可欠です。
• 記載内容: ネットワーク構成、サーバー構成（役割ごとのグルーピング）、利用しているクラウドサービス（AWS, GCPなど）、外部サービス連携の概要など。

監視体制とアラート体系

• 目的: 「何が」「どのように」監視され、「どのような状態」でアラートが発報されるのかを明確にするため。アラートを受け取った担当者が、その重要度と影響範囲を即座に判断できるようにします。
• 記載内容: 監視ツール（Datadog, Mackerel, Zabbixなど）、主要な監視項目（CPU使用率, メモリ使用率, ディスクI/O, サービス死活監視）、アラートの閾値とレベル（Critical, Warning, Info）、通知先（Slack, PagerDuty, Emailなど）。

障害対応フロー

• 目的: 運用マニュアルの核となる最重要項目。アラート検知からインシデントのクローズまで、担当者が取るべき行動をステップ・バイ・ステップで定義します。これにより、パニックに陥らず、冷静で一貫した対応が可能になります。
• 記載内容: 検知、一次切り分け、原因調査、関係者への連絡、暫定対応、恒久対応の起票、復旧確認、事後報告といった一連の流れ。

定期メンテナンス手順

• 目的: 日次、週次、月次などで行われる定型業務の手順を標準化し、作業ミスや漏れを防ぐため。
• 記載内容: OSパッチ適用、ミドルウェアのアップデート、ログローテーション、バックアップ取得・リストアテスト、証明書の更新など、具体的なコマンドや確認項目を含めた手順。

エスカレーションルール

• 目的: 一次対応者だけでは解決できない問題が発生した際に、「誰に」「どのタイミングで」「どのような情報をもって」助けを求めるかを定義するため。問題の滞留を防ぎ、迅速な解決に繋げます。
• 記載内容: 障害の深刻度や発生からの経過時間に応じたエスカレーション先（二次対応者、開発チーム、インフラチーム、責任者）、連絡手段、報告すべき情報テンプレート。

既知の問題とFAQ

• 目的: 過去に発生した障害や、よくある問い合わせを蓄積・共有することで、同様の問題に迅速に対応できるようにするため。ナレッジベースとしての役割を果たします。
• 記載内容: 発生した事象、原因、行った対処、恒久対応の有無や内容。

復旧・切り戻し手順

• 目的: デプロイや設定変更後に問題が発生した場合に、安全かつ迅速にシステムを正常な状態に戻すための手順を明確にするため。攻めの変更を支える「安全弁」となります。
• 記載内容: デプロイ前のバージョンへのロールバック手順、機能フラグのOFF手順、DBのポイントインタイムリカバリ手順など。

連絡先・体制図

• 目的: インシデント発生時に必要な関係者へ迅速に連絡を取れるようにするため。
• 記載内容: 運用チーム、開発チーム、インフラチーム、各責任者、さらには外部ベンダーの連絡先と、緊急度に応じた連絡手段（電話、チャットなど）。

これらの要素をテキストで記述し、要所にMermaidで作成した構成図を埋め込むことで、視覚的で理解しやすい「生きた運用マニュアル」が完成します。

第2章: Mermaidで作る！運用マニュアルの中核をなす構成図サンプル5選

それでは、前章で挙げた構成要素を視覚化するための、具体的で実践的なMermaidサンプルを見ていきましょう。すべてdirection LR（左から右）を基本とし、コピー＆ペーストしてすぐに使えるように解説します。

アイデア1: 究極に実践的な「障害対応フローチャート」 (flowchart LR)

障害対応フローは、運用マニュアルで最も参照される図です。ここでは、アラートの深刻度や原因特定の可否による分岐を含んだ、現実的なフローチャートを作成します。

なぜ有効か？ パニック状態でも、次に何をすべきかが一目瞭然になります。判断の分岐点を明確にすることで、担当者のスキルレベルに依存しない、標準化された対応を実現します。

Mermaidコード例:

flowchart TD
    subgraph "フェーズ1: 検知・初期対応"
        A[🚨 アラート検知] --> B{深刻度は？};
        B -->|Critical| C[PagerDutyで担当者呼び出し];
        B -->|Warning| D[Slackへ通知];
        C --> E[インシデント責任者へ第一報];
        D --> F[担当者がアサイン];
        E --> F;
    end

    subgraph "フェーズ2: 切り分け・調査"
        F --> G{影響範囲の特定};
        G -->|広範囲/コア機能| H[全社ステータスページ更新];
        G -->|限定的| I[一次切り分け開始 ログ/メトリクス確認];
        H --> I;
        I --> J{原因の特定は可能か？};
    end

    subgraph "フェーズ3: 復旧対応"
        J -->|はい| K[復旧手順を実施 切り戻し or 暫定対応];
        J -->|いいえ| L[開発/インフラチームへ調査依頼];
        L --> M[合同で調査・対応];
        K --> N[復旧確認];
        M --> N;
    end

    subgraph "フェーズ4: 事後処理"
        N --> O{復旧したか？};
        O -->|はい| P[インシデントクローズ 関係者へ最終報告];
        O -->|いいえ| L2[再度、開発/インフラへ調査依頼]; 
        P --> Q[ポストモーテム実施 恒久対応を起票];
    end

    %% クリックイベントで詳細ドキュメントへリンク (GitHub/Confluenceなどで有効)
    click I "#section-primary-check" "一次切り分け手順へ"
    click K "#section-recovery-procedure" "復旧手順一覧へ"
    click L "#section-escalation-rule" "エスカレーションルールへ"

解説:

• subgraph を使って対応フェーズをグルーピングし、全体の流れを把握しやすくしています。
• {}（ひし形）で「深刻度」「原因特定可否」といった判断ポイントを明確に示しています。
• |text| を使って、分岐の条件を矢印に記述しています。
• click 命令（コメントアウト部分）は、対応するMarkdownレンダラ（GitHubなど）で有効になり、図のノードをクリックすると指定したページ内リンクやURLにジャンプさせることができます。これにより、図から詳細な手順書へとシームレスに移動でき、マニュアルの利便性が飛躍的に向上します。

アイデア2: システム構成と監視ポイントの関連図 (graph LR)

どのコンポーネントを、どのツールで監視しているのか。この関係性を視覚化することは、アラートの意味を理解する上で非常に重要です。

なぜ有効か？ 「このアラートは、システムのどの部分の問題を示唆しているのか」が直感的に理解できます。原因調査の初動で、当たりをつけるべき範囲を絞り込むのに役立ちます。

Mermaidコード例:

graph LR
    subgraph "監視ツール"
        M[Mackerel]
        D[Datadog]
        P[PagerDuty]
    end

    subgraph "ユーザーリクエスト"
        User[👤 User] --> LB[ALB];
    end

    subgraph "本番環境 (Production)"
        LB -- "Port 80/443" --> WEB(Web/APサーバー群);
        WEB -- "DB Connection" --> DB[(RDS Aurora)];
        WEB -- "Cache" --> ELC[(ElastiCache)];

        subgraph "監視詳細"
            M -- "死活・リソース監視" --> WEB;
            M -- "リソース監視" --> DB;
            D -- "APM・外形監視" --> WEB;
            D -- "Slow Query" --> DB;
        end
    end

    subgraph "アラート通知"
        M -- "Alerts" --> P;
        D -- "Alerts" --> P;
        P -- "Call/SMS/Chat" --> Ops[👨‍💻 運用担当];
    end

    %% スタイル定義
    style WEB fill:#f9f,stroke:#333,stroke-width:2px;
    style DB fill:#ccf,stroke:#333,stroke-width:2px;
    style M fill:#9cf,stroke:#333,stroke-width:2px;
    style D fill:#f99,stroke:#333,stroke-width:2px;

解説:

• ここでも subgraph を活用し、「監視ツール」「本番環境」「アラート通知」といった役割でコンポーネントを整理しています。
• () で囲むと角丸のノード、[()] で囲むとデータベースのような形状のノードになり、コンポーネントの種類を視覚的に区別できます。
• 矢印に -- "text" --> のようにラベルを付けることで、通信内容（ポート、接続種別）や監視内容（死活監視、APM）を明記できます。
• style 定義を使えば、特定のノードに色を付けるなど、より視認性の高い図を作成できます。

アイデア3: 定期メンテナンスのシーケンス図 (sequenceDiagram)

関係者が複数にまたがる作業は、フローチャートよりもシーケンス図の方が時間軸と役割ごとのやり取りを明確に表現できます。

なぜ有効か？ 「誰が」「誰に対して」「どの順番で」作業や連絡を行うべきかが一目瞭然となります。作業の抜け漏れや、担当者間の認識齟齬を防ぎます。

Mermaidコード例:

sequenceDiagram
    participant Ops as 運用担当者
    participant Dev as 開発チーム
    participant Svc as 対象サービス
    participant User as 顧客サポート

    Ops->>User: メンテナンス実施の事前通知 (3営業日前)
    User->>Ops: 承諾

    loop メンテナンス当日
        Ops->>Svc: メンテナンスモードに移行
        Ops->>Ops: ① DBバックアップ取得
        Ops->>Dev: バックアップ完了、デプロイ開始を依頼
        Dev->>Svc: ② アプリケーションをデプロイ
        Dev->>Ops: デプロイ完了報告

        Ops->>Ops: ③ 基本的な動作確認 (疎通確認)
        alt 動作に問題あり
            Ops->>Dev: 問題発生を報告、調査依頼
            Dev->>Ops: 調査・修正対応
        else 動作に問題なし
            Ops->>Ops: 正常動作を確認
        end

        Ops->>Svc: メンテナンスモードを解除
        Ops->>User: メンテナンス完了を報告
    end

解説:

• participant で登場人物（またはシステム）を定義します。as を使って別名を付けると、図がすっきりします。
• ->> は実線の矢印で、メッセージのやり取りを表します。
• loop ブロックは繰り返し行われる一連の作業を囲みます。
• alt/else ブロックは条件分岐を表し、「問題があった場合」と「なかった場合」のフローを明確に分けて記述できます。

アイデア4: エスカレーションパスのタイムライン (gantt)

障害発生からどれくらいの時間で、誰にエスカレーションすべきか。この時間的な制約（SLA）を視覚化するには、ガントチャートが意外なほど有効です。

なぜ有効か？ 障害対応のタイムリミットを視覚的に意識させることができます。「あと何分で次のアクションを起こさねばならないか」が明確になり、対応の遅延を防ぎます。

Mermaidコード例:

    title Critical障害発生時のエスカレーションタイムライン
    dateFormat  HH:mm
    axisFormat  %H:%M
    section 一次対応 (担当者)
    初期対応            :crit, 00:00, 15m
    原因調査と暫定対応  :crit, after 00:00, 30m

    section 二次対応 (チームリーダー/専門チーム)
    エスカレーション受付  :done, 00:30, 5m
    詳細調査            :active, 00:35, 60m

    section 三次対応 (責任者/マネージャー)
    状況報告と判断      :01:35, 10m

    section 全体
    ステークホルダーへの第一報 :milestone, 00:10, 2m
    30分ごとの状況アップデート :milestone, 00:30, 2m
    60分ごとの状況アップデート :milestone, 01:00, 2m

解説:

• gantt を使うことで、時系列に沿ったタスクの期間を表現できます。
• title で図の目的を明確にします。
• section で対応レベル（一次、二次）を区切ります。
• タスク名 :ステータス, 開始時間, 期間 の形式で記述します。crit（クリティカル）や active（作業中）といったステータスで色分けも可能です。
• milestone は特定の時点でのイベントを示し、「いつ報告すべきか」という重要なアクションを明示するのに役立ちます。

アイデア5: インシデントのライフサイクル（状態遷移図 stateDiagram-v2）

一つのインシデントチケットが、発行されてからクローズされるまでにどのような状態をたどるのか。このライフサイクルを定義することで、チーム全体のインシデント管理プロセスが統一されます。

なぜ有効か？ インシデントのステータスが何を意味するのか、チーム全員が共通認識を持つことができます。チケット管理ツール（Jira, Redmineなど）の運用ルールを補完する図として最適です。

Mermaidコード例:

stateDiagram-v2
    direction LR
    [*] --> New: インシデント検知

    New --> Investigating: 担当者が調査開始
    Investigating --> Identified: 原因を特定
    Investigating --> Escalated: 解決できずエスカレーション

    Escalated --> Investigating: 上位チームが調査引き継ぎ

    Identified --> Resolved: 復旧対応が完了
    Resolved --> Closed: 復旧を確認しクローズ
    Resolved --> Reopened: 再発 or 復旧不十分

    Reopened --> Investigating: 再調査開始

    Investigating --> Closed: 対応不要と判断(誤報など)

    note right of Identified
      恒久対応が必要な場合は
      この段階で別チケットを起票する
    end note

解説:

• stateDiagram-v2 を宣言し、direction LR を指定します。
• [*] は開始点を示します。
• 状態A --> 状態B: イベント の形式で、どのようなアクション（イベント）によって状態が遷移するかを記述します。
• note を使うことで、図の特定の部分に補足説明を追加でき、プロセスの運用ルールなどを書き添えるのに便利です。

第3章: 作図のコラボレーションと表現力を高める次の一手 - Cacooという選択肢

ここまでMermaidの強力な機能と、運用マニュアルへの応用例を見てきました。テキストベースでバージョン管理できる手軽さとスピード感は、日々のドキュメント更新において絶大な効果を発揮します。

しかし、運用ドキュメントを作成する中で、こんな壁にぶつかることはないでしょうか。

• 「もっと複雑なAWSアーキテクチャ図を描きたいけど、Mermaidのレイアウト調整が難しい…」
• 「非エンジニアのメンバーにも、レビューや修正を気軽にお願いしたい」
• 「お客様向けの報告書に使うため、もっと見栄えの良い、公式アイコンを使った図が必要だ」

Mermaidは素晴らしいツールですが、万能ではありません。特に、緻密なレイアウト調整、リッチなビジュアル表現、そしてチーム全体を巻き込んだ共同作業においては、専門のツールに軍配が上がることがあります。

そこで、ほんの少しだけ紹介したいのが、私たちヌーラボが開発・提供するビジュアルコラボレーションツール Cacoo です。

![CacooのロゴやUIのイメージ画像をここに配置]

Cacooは、Mermaidが持つ「コードとしてのドキュメント」という思想とは異なるアプローチで、チームの作図体験を革新します。

Cacooが解決する、Mermaidの"あと一歩"

• 直感的なUIと自由なレイアウト: Cacooはドラッグ＆ドロップで直感的に操作できるGUIツールです。コンポーネントの配置、線の引き方、大きさの調整など、思い通りのレイアウトをピクセル単位で実現できます。複雑なネットワーク構成図やシステムアーキテクチャ図も、ストレスなく作成できます。
• 豊富なテンプレートと図形ライブラリ: Mermaidでは表現が難しい、クラウドサービスの公式アイコン。Cacooなら、AWS、GCP、Azureなどのアイコンが豊富に用意されており、誰でもプロフェッショナルな構成図を素早く作成できます。ワイヤーフレームやマインドマップなど、運用マニュアル以外の用途で使えるテンプレートも充実しています。
• 最強のコラボレーション機能 ― "作図"をチームの対話の場に: Cacooの真価は、そのコラボレーション機能にあります。
  • リアルタイム同時編集: 複数人が同じキャンバス上で、同時に図を編集できます。オンライン会議をしながら、全員で認識を合わせてアーキテクチャを議論し、その場で図に反映させていく、といった使い方が可能です。
  • コメント機能: 図の特定の部分にピンポイントでコメントを残せます。「ここの接続は本当に正しい？」「このサーバーの役割を追記して」といったレビューやフィードバックが非常にスムーズに行えます。これにより、図のレビューが活性化し、ドキュメントの品質が向上します。
  • バージョン管理と共有: Cacoo上ですべての変更履歴が保存され、いつでも過去のバージョンに戻せます。完成した図はURLで簡単に共有でき、ブログやWikiへの埋め込みも可能です。

ハイブリッドアプローチという賢い選択

私たちは「Mermaidを捨ててCacooを使おう」と言いたいわけではありません。むしろ、両者の強みを活かしたハイブリッドなアプローチが最も現実的で効果的だと考えています。

• 日常のフローや手順書: 変更頻度が高く、シンプルなものは Mermaid で。Gitでバージョン管理し、エンジニアが手軽に更新できるようにする。
• システムの全体像や顧客向け資料: 見栄えと正確な表現が求められ、チームでのレビューが重要なものは Cacoo で。リッチな図形とコラボレーション機能を活用し、質の高いドキュメントを作成する。

Cacooで作成した図は、PNGやSVG形式でエクスポートし、Mermaidを使っているMarkdownドキュメントに画像として貼り付けることができます。これにより、テキストベースの管理の容易さと、ビジュアルツールの表現力を両立させることが可能です。

運用マニュアルの作成は、孤独な作業であってはなりません。チーム全員が参加し、対話し、改善していく文化を育むこと。Cacooは、そのための「対話の場」を提供します。

結論: "生きた"マニュアルは、チームを強くする

本稿では、「運用マニュアル」をテーマに、Mermaidを活用した具体的な構成図のアイデアを多数紹介し、さらにチームでの作図体験を向上させるCacooという選択肢を提示しました。

重要なのは、運用マニュアルを「一度作ったら終わりの静的な成果物」ではなく、**「チームと共に成長し続ける、生きたプロダクト」**として捉えることです。

• Mermaid は、その「生きたプロダクト」をコードとして管理するための強力な武器となります。
• Cacoo は、そのプロダクトをチーム全員で育てていくための、温かい対話の場を提供します。

あなたのチームに最適なツールとワークフローを選択し、変化に強く、誰にとっても分かりやすい「生きた運用マニュアル」を育てていってください。そのドキュメントは、単なる手順書を超え、安定したサービス運用と、チームの技術力・文化を支える、確かな資産となるはずです。