現場で「作ったけれど使われない」ドキュメントに悩んでいませんか。忙しい担当者は文章を読まず、質問はサポートに直行します。この記事では、既存のRunbookやログ、サポート履歴を素材にして、Pythonで操作マニュアル・FAQ・チェックリスト・理解度クイズを自動生成し、配布と更新、効果測定まで回す実務ワークフローを示します。小さく試せて継続しやすい方法に焦点を当てます。
導入の勘所
現場定着を目指す際は「誰が」「いつ」「どのシチュエーションで」ドキュメントを参照するかを最初に決めます。目的が曖昧だと情報は増えても使われません。次の点を最初に確認してください。
- 利用者の役割（オペレーター、担当者、マネージャ）と想定シナリオ
- 最小限で運用できる成果物（HTMLマニュアル、FAQ、チェックリスト、クイズ）
- 更新頻度と責任者（自動ジョブ＋確認者の組み合わせ）
既存資産の棚卸（Runbook・ログ・サポート履歴）
まずはソースを可視化します。手作業でのレビューが難しい場合は正規表現やメタデータ抽出で候補を拾い上げ、優先度付けします。
収集すべきデータの例
| ソース | 抽出内容 | 優先度の目安 |
|---|---|---|
| Runbook | 手順、前提条件、実行コマンド | 高 |
| 障害ログ | 頻出エラー、復旧手順 | 高 |
| サポート履歴（チケット） | よくある質問と回答、作業時間 | 中〜高 |
| 操作画面のスクショ/ドキュメント | 画面遷移、注意点 | 中 |
ドキュメント設計（役割別・シナリオ別）
役割とシナリオを軸に、成果物の粒度と配布方法を決めます。現場が求めるのは「すぐ使える手順書」と「すぐに確認できるFAQ」です。
成果物の例と用途
| 成果物 | 用途 | 配布先の例 |
|---|---|---|
| HTMLマニュアル（h2/h3構成） | 初回導入と参照用 | イントラWiki、Webページ |
| FAQページ | 頻出質問への即応 | FAQセクション、チャットボット連携 |
| オンボーディングチェックリスト | 初期学習と作業完了の可視化 | Google Sheet、CSV |
| 理解度クイズ（自動採点） | 学習到達度の確認 | CSVインポート、管理画面 |
Pythonでの自動生成ワークフロー（コード・テンプレート）
ここでは実装の主要ステップを示します。詳細なコードはプロジェクトに合わせて調整してください。
1) RunbookやFAQ候補の抽出（正規表現・メタデータ）
テキストファイルやチケットエクスポートから、見出し・コマンド・エラーコードを抽出します。抽出ロジックはシンプルにして、後で人手で補正できるように運用します。
| 処理 | 例（擬似コードの説明） |
|---|---|
| ファイル走査 | 対象ディレクトリの.md/.txt/.csvを読み込む |
| 見出し抽出 | 正規表現で^#{1,3}\s+を検出してセクション化 |
| コマンド・エラー抽出 | r”\b(error|failed|Exception)[:\s]”で候補抽出 |
2) LLMプロンプトテンプレートで手順を平易化—安全ガード付き
手順の自然言語化にはプロンプトテンプレートを用意し、禁止事項や安全策を明示してガードをかけます。出力は必ず原文と突き合わせるワークフローにします。
| テンプレート項目 | 内容（例） |
|---|---|
| 業務概要 | 対象システムと目的（例：バックアップ復旧手順） |
| 禁止事項 | 認証情報の出力禁止、実行権限の明示 |
| 出力形式 | HTMLのh2/h3と手順の番号付きリストで返す |
3) HTMLテンプレートに差し込むPythonスクリプト（サンプル）
テンプレートはプレーンなHTMLで用意し、{{title}}や{{steps}}のようなプレースホルダを文字列置換します。小さいテンプレートから始めると運用が楽です。
| テンプレート例（抜粋） | 説明 |
|---|---|
| <h2>{{title}}</h2><div class=”steps”>{{steps}}</div> | 単純な置換でHTML生成 |
| {{steps}}に<h3>手順1</h3><p>…</p>を組み立てる | 生成されたテキストを安全にエスケープし挿入 |
4) 簡易クイズの自動生成と採点ロジック（CSVベース）
理解度チェックはCSVで管理します。問題・選択肢・正答を列にし、Pythonで採点する仕組みが最も手を出しやすいです。
| quiz.csvフォーマット | 説明 |
|---|---|
| id,question,option_a,option_b,option_c,answer | answerはa/b/cで管理 |
| 1,”復旧手順で最初に確認する項目は？”,”ログの有無”,”権限確認”,”設定ファイル” ,b | CSVを読み込んでランダム出題・採点 |
5) 定期更新ジョブ（cron/airflow）と差分通知（Slack webhook）
定期ジョブで新しいログやチケットを取り込み、差分がある場合はドラフトを再生成して差分をSlackやメールで通知します。自動更新は必ずレビューステップを入れてください。
| 配布メッセージ例（Slack） | 用途 |
|---|---|
| 「自動生成ドキュメントのドラフトが作成されました。差分確認: |
更新の存在をチームに通知 |
配布・更新フロー
配布は自動化と有人確認のハイブリッドが現実的です。自動配布は到達率を上げ、有人レビューは誤情報の混入を防ぎます。
運用フロー（例）
- 夜間バッチがソースを収集→ドキュメントを生成（ドラフト）
- 担当者が差分レビュー（24時間以内）→承認で公開
- 公開後、Slack/メールで対象者に配布（ターゲット指定）
- 配布後に簡易クイズを送付し、理解度を確認
効果測定と改善サイクル
現場定着の評価は定量的指標と定性的フィードバックの両方で行います。数値に偏りすぎないことが重要です。
導入時のKPIと更新トリガー
| KPI項目 | 目標（導入初期の目安） |
|---|---|
| 到達率（ドキュメントを開いたユーザー割合） | 50〜70%（初月） |
| 初回成功時間（タスク完了までの時間） | 既存比で20%短縮目標 |
| サポート件数減少 | 問い合わせ数の10〜30%減 |
更新トリガーとチェックリスト
| トリガー | アクション |
|---|---|
| FAQヒット率の増加 | FAQの詳細化またはチュートリアルの追加 |
| 特定エラーの問い合わせ増 | Runbookの該当手順を分かりやすく改訂 |
| クイズの正答率低下 | 該当分野のトレーニング教材を再配布 |
よくある失敗パターンと回避法
| 失敗パターン | 回避法 |
|---|---|
| 自動生成をそのまま公開して誤情報を出す | 必ずレビューステップを設け、サンプルカバレッジを用意 |
| 配布対象を絞らず通知が埋もれる | ロールベースでターゲティングする |
| 更新頻度が高すぎて追えない | 重要度に応じた公開ルールを設定（重大:即公開、軽微:月次まとめ） |
まとめ
現場で使われるドキュメントを作るには、自動化だけでなく「運用設計」と「小さなレビュー流れ」が必要です。この記事で示した流れは次のように始められます。
- まずはRunbookとサポート履歴を1週間分抽出して候補を作る
- 簡易HTMLテンプレートとquiz.csvを用意して、Pythonで一度全体を生成する
- 担当者のレビューとSlack通知を組み合わせて、1サイクル運用してみる
次の一歩としては、生成ドキュメントの自動テスト導入（第44回参照）や、利用状況をモデル運用のメトリクスに取り込み学習データとして反映することを検討してください（第40回／第36回との連携）。小さく確実に回し、現場の負担を減らす習慣を作ることが成功の鍵です。