こんにちは。マネージドサービス課の橋本です。

近年の将棋界は話題豊富で素晴らしいですね。最近のトピックだと

藤井聡太「六段」が誕生
藤田綾女流二段が入籍
名人戦、史上初の6人プレーオフ

このあたりが話題を呼びました。

藤田綾女流二段は日曜日お昼のNHKでは最早お馴染みの顔です。入籍にショックを受けたファンが多数いるとかいないとか。

藤井聡太六段は言わずもがなですね。藤井六段が将棋界のニューヒーローであることは衆目一致するところでしょうが、若手の活躍は彼だけに留まりません。佐藤天彦名人、中村太地王座、菅井竜也王位といった若手タイトルホルダーの台頭は新時代の到来を実感させます。

将棋楽しいですよ。将棋始めましょう。

はじめに

では、本題に入ります。Excel方眼紙に苦い思いをされた方はそれなりに多数いらっしゃるのではないでしょうか。

運用の改善業務を進めていく立場としては、Excelベースの手順書改修ってなかなか難儀な作業ですよね。高々数行の手順を挿入するために、挿入以降の工程で大幅にレイアウト修正が必要になって涙目...こんな経験、Excelerな諸氏であれば一度はあるのではないでしょうか。このような作業に時間を浪費して生産性を落とすのは、あまりにもったいないと思います。

このような無駄は削減して、もっとお客様のために使う時間を増やしていきたいものです。レイアウト地獄のExcel方眼紙から脱却しましょう。

この記事は、Excelに頼らず、改善サイクルが回しやすいドキュメント管理環境を実現するためのネタとして書きました。今回の目的は本格的な検証ではなく、手早くアイデアを試せる環境を手に入れることです。こういう環境だったらいいなー、っていう妄想をさらっと実装してみました。

概要

最終的には、Excelベース + ファイルサーバーな手順書管理の代替案として、後述の構成を作ってみた、という話に着地します。

前提条件として、幾つか「現場」の想定を記載します。

運用とは「手順書で定められた定常運用」を主業務とする現場を想定しています。障害対応などの非定常運用は想定していません
想定編集者は末端の作業者も含めた現場スタッフです。技術力があまり高くない方が編集業務を受け持つことも想定範囲です

なお、環境構築に関わる部分の解説はまた別の機会に執筆する予定です。今回は問題提起とか、改善のアイデアを中心にご紹介します。

構成図

今回の構成図は下図の通りです。この図のCI周りは、アプリ開発だとそこそこポピュラーな構成だと思います。これを運用ドキュメントの世界でやってみたら面白いんじゃないか？というところから着想を得ています。

この構成のアピールポイントは以下になります。

Excelベースからテキストベースへの移行
- テキストベースのため変更や加筆が容易になり、編集の心理的/物理的負担を軽減
- 変更管理をバージョン管理システムに任せることができる（バイナリフォーマットでは差分が見えない）
ドキュメンテーションビルドシステムを使うことで編集者/作業者双方のニーズを両立
- 編集者は共通要素を1箇所のソースで管理したい
- 作業者は1つの作業を1つの手順書の中で完結させたい
ビルド環境としてDockerを採用
- ビルドシステムが入れ替わっても、大規模な構成変更が発生しない。基本的にはCIツールのコンフィグ変更とDockerイメージの差し替えだけでOK
- ライブラリが古くなってもレポジトリにビルド環境が残るため、延命措置が取りやすい
レビュー〜リリースまでのプロセスが透明になる
- レビュー方法はメールベース卒業、GitHub上のやりとりになる
  - GitHubを見れば、レビューのステートが誰の目にも明瞭にわかる
  - 過去の変更履歴はレポジトリのコミットログやプルリクを追っていけば良い。メール大捜索の手間は要らない
- pushトリガーの自動ビルド・自動デプロイに対応
  - プルリクがmasterにmargeされれば自動的に手順書がリリース！
  - SlackのWebhookなどを組み合わせて、リリース時のアナウンスも容易に自動化できる
サーバーレス
- 構成要素は全てSaaSやフルマネージドサービス。インフラにかけるコストも安上がり

問題提起

あくまで私見です。ご了承ください。

Excelってどうなの

そもそものスタートが「Excel方眼紙脱却したい」なので、まずは手順書のフォーマットとしてExcelを使うことの是非を述べます。スタンス的に当然ですが、結論はデメリットの方が大きい、ということになります。

Excel手順書ここが素敵

Excel手順書も、別に悪いことばかりではありません。メリットはあると思います。特筆すべきは以下の2点だと思います。

ツールの学習コスト
単一ファイルでの管理が可能

日々の運用に追われる現場のスタッフが手順書改修を継続的に実施していくためには、どのような環境が必要でしょうか。少なくとも私は、編集という作業のハードルを低く保つことが重要だと考えます。そのため、どんな現場でも「誰でもある程度は使える」ことが期待できるExcelを選択することは理に適うと思います。

単一ファイルでの管理が可能であることもメリットだと思います。運用の規模が大きくなれば、引き継ぎや規模の拡大を経て、情報の管理は難しくなっていきます。単一ファイルでの管理ができれば、少なくとも「ハイパーリンクで参照してる別手順がリンク切れしてる！」などという類の騒ぎは未然に防げます。情報を管理する上でエントロピーは低いほうが良いに決まってます。

Excel方眼紙ここがイヤだ

ざっと挙げてみます。

ちょっとした手順挿入でもレイアウト変更が入ってとにかく手間
- レイアウト調整の作業に工数が取られる
- 本質でない付随作業にも工数が取られる状況が続くと、改修タスクに対する心理的なハードルも上がる
- 結果、継続的に(手順書を)改善していく文化が根付きにくくなる
共通的な汎用手順が各作業手順書埋め込みになってしまう
- 更新の手間が増える
- 更新漏れのリスクも増える
変更履歴の管理が煩雑
- 「変更内容の把握と記録」が人力仕事になってしまっている
- バイナリなのでGitHubなどに乗せてもメリットが薄い（diff見えない・プレビューできない）
- レビューの履歴はメールなどの外部システムに外出し
  - メールの履歴から過去経緯を追う作業はしんどい上に、成果が上がる保証もない

要約すると 「修正作業の煩雑さ」と「変更履歴の管理」 に集約できると思います。

「誰でも使えるツール」であることは初期の学習コストを軽減してくれます。それは確かにメリットですし、導入時点だけを見れば合理的判断に見えます。しかし、未来の運用現場において、いずれはその判断のツケを管理コストで支払うタイミングがやってきます。

もちろん、Excelベースでうまく回っている現場も存在するとは思います。でも、そもそもExcelって本来表計算ソフトです。ドキュメント管理の枠組みでやっていくには、多少なり人力でフォローする部分があるのではないでしょうか。それならば、はじめからシステムの力でドキュメント管理をうまく回せる仕組みを作ってしまう方が生産的なんじゃないかなと思います。

「扱いやすい」手順書

作業する人と手順を書く人、必ずしも同一ではないと思います。

立場が変わると、「扱いやすい手順書」の見え方は違います。

一時期の私は作業者としての業務を中心にしていました。なので作業者寄りの立場で書きます。

作業者観点

少なくとも、作業者が業務を実施するにあたっては「1つの手順書は1つの場所」に置かれている方が良いでしょう。オペミスを防ぐ観点において、「1つの作業は1つの手順書の流れを追えば完結できる」がとても重要だと考えます。

例えば、作業手順の各工程がハイパーリンクであちこちに飛んで、また戻る...というドキュメント。これは作業をする上であまり良いフォーマットとは言えないと思います。

このような手順書を使うと、「上から下に、順番に」という作業の流れを作ることが難しくなります。結果、現在の工程がどこであったか、見失ってしまう確率が上がります。定常運用を行う現場において、作業者フレンドリーでない手順書は、現場全体のオペミスリスクを引き上げます。

編集者観点

ドキュメント編集者の立場では、共通手順は1つのソースにまとめたいと思うものです。同じソースを多重管理すると、変更時の手間は増加し、更新漏れのリスクが高まります。前節で挙げた、共通手順をハイパーリンクで参照するやり方は、編集者の都合では合理的な方法です。しかし、 それをそのまま手順書に落としてしまうと、作業者にとっては読みづらい手順書になってしまっている 可能性があります。

どのようなフォーマットにせよ、実際に手を動かす作業者の方にとって見づらい手順書ならそれは「良い手順書」とは言えません。

どうしたら良いのか

ここまでの流れを踏まえて、どのような手を打つのが良いのか考えてみました。

この記事の執筆開始時点で、以下のようなやり方が有力と考えています。この仕組みを実装したものが冒頭の構成図となります。

Markdownへの移行

手順書フォーマットはテキストベースを大前提とします。これにはいくつかの利点があります。

編集の手間が減る
- Excelで味わうような、レイアウト調整は基本的に不要になる
- 追加手順の挿入や工程順序の入れ替えなどはテキストブロックのコピペでOK
バージョン管理システムの力を使えるようになる
- テキストなら過去のdiffも容易にとれる
- 変更の経緯/背景などの引き継ぎづらい情報をコミットメッセージ/issue/プルリクなどに残せる

フォーマットには、それなりの表現力があって覚えるのも簡単な「Markdown」の採用を前提に考えました。Sphinxがサポートする「Restructured Text(reST)」も選択肢に上がりましたが、記法がシンプルであること重視して今回はMarkdownを選びました。

ドキュメンテーションビルドシステムの導入

作業者と編集者の間には、一見相容れないニーズがあるように見えます。

作業者は、1つの作業手順を流れで追えるような状態であって欲しい
編集者は、汎用的な作業工程は1つのソースにまとめて管理したい

双方のニーズを満たすための手段としてはドキュメンテーションビルドシステムの導入が検討できます。代表的なのはSphinxです。こちらも検討しましたが、サーバー(=EC2)を立てるのが面倒だったのと、reSTが個人的にとっかかりづらかったことが今回の趣旨に沿わず、不採用です。きちんと検証するならSphinxは最有力の一角だと思います。

Markdownをデフォルトでサポートするものはないかと眺めていた時、良さそうなのはmkdocsかなと思いました。拡張機能の導入が必要となりますが、別ファイルのincludeもサポートされています。汎用手順の一元管理はこれで実現可能です。

mkdocsはスタンドアロンで動作しますので、ローカルでの確認もお手軽です。細々した確認はmarkdownエディタのリアルタイムプレビューで賄いつつ、キリのいいところまで書けたら今度はローカルのmkdocsでビルド結果を確認する、という流れで普段の編集業務を進めていくことになります。

GitHub ✕ CIツールでビルド〜リリースを自動化

リリース版のデプロイ手段が必要です。そのあたりの仕組みとしてGitHubとCircleCI（+dockerレジストリ）を使いました。

Markdownドキュメントの作成後、本番環境へ適用するためには以下のステップを踏むことになります。

mkdocs build でhtmlを生成
生成されたコンテンツ一式をWebサーバー(S3)に配置

今回の構成で、これらのプロセスを自動化します。

mkdocsがインストールされた環境をDockerコンテナとして作成し、Dockerレジストリ(Docker HubやAmazon ECR)にpushしておきます。CircleCIのビルド環境に、このDockerイメージを指定します。

GitHubとCircleCIを連携させ、pushイベントに連動してビルド〜デプロイコマンドが実行されるよう設定します。デプロイにはAWS-CLIコマンドの aws s3 sync を使用して、ビルドの成果物(html/css/js)一式をS3バケットにデプロイします。デプロイはこれ一発でOKです(※)。

※参考 ... aws s3 sync に --delete オプションを付けると、差分を考慮して不要になったファイルのお掃除も一緒にやってくれます。そのため、更新デプロイを行う時もこのコマンド1発で用事が済んでしまいます。地味ながら非常に有用です。

まとめ

今回のシステムでどういうことがしたかったかというと、以下の点になります。

Excelやめるための手立てを考える
手順書を簡単に改修できる環境を手に入れる
変更経緯やバージョンの管理は、それを得意とするシステムの力を活用する（≒活用できる環境を作る）

割とやりたいことは実現できたような気がします。ですが、まだまだ本番運用に乗せる検討はできません。個人的に検証サイクルも回してみましたが、それによって課題も見えてきました。特に気にしているのは以下のポイントです。

編集者の負担をもっと下げる

「現場」の想定を再掲します。

想定編集者は末端の作業者も含めた現場スタッフです。技術力があまり高くない方が編集業務を受け持つことも想定範囲です

このため、編集者に求められる技術要素は少ないほうが良いです。

特に git の使用がハードルになりえます。できれば、gitの利用は必須要件から外れるよう調整し、Markdownの記法だけ覚えられえばいいような仕組みにしたいです。今のところ、これは今後の課題です。

Markdownの表現力と可搬性

Markdownのincludeに対応するために別途拡張を入れる必要であると述べましたが、そのあたりが課題になります。

私自身のニーズとしてはinclude構文のサポートと見出し番号の自動採番 の2点がほぼ必須要件となるのですが、これらの仕様はどうやらMarkdownで標準化されておらず、デファクトと呼べる拡張もなさそうでした。ビルドシステムの独自拡張を用いればこれらの要件は満たますが、その代償として作成したドキュメントが実質的に特定のビルドシステムにロックされてしまいます。

将来に渡って mkdocs がメンテされている保証などありません。プロダクションの運用ならば、ドキュメントのライフサイクルは長めに想定する必要があります。そのため、手順書を書くための必要最低限として求められる表現力は言語標準、もしくはデファクトスタンダードでサポートしていて欲しいところです。

記法がシンプルであることを重要視して今回Markdownを選びましたが、現時点では、可搬性の観点でMarkdownは今回の要件に採用しづらいと言うことがわかっています。こちらも今後の検討課題です。

このシステムの引き継ぎ

いくつかの要素が組み合わさる構成なのでちょっと引き継ぎに難儀しそうです。運良く技術者のアサインができれば良いですが、そうならない可能性も想定範囲にしておくべきでしょう・・・。システム構成そのものも、よりシンプルである方が望ましいと思います。

この話の殆ど前提になる部分を覆しますが、DocBaseやConfluenceといったSaaSサービスをドキュメント管理に利用する手は有力だと思います。また、markdownベースでドキュメントの要件が満たせるのならば、プロジェクト管理のSaaSであるBacklogも有力です。Backlogの機能としてGitレポジトリが使えますので、チケット管理と組み合わせて運用していくのは非常にアリだと思います。やり方は色々あると思います。

おわりに

課題は残るものの、プロトタイプとしてはそれなりに面白いものが作れたのではないかと思っています。また、この試みを通すことで、ガチで手順書管理の環境を整備するならmarkdownは私の要件に噛み合わないらしい、ということもわかってきました。やはりSphinxが安定かも知れません。

今回のネタは私のGitHubに公開されている（ビルド環境のDockerfileとかCircleCI/CodeBuildのコンフィグとか）のですが、雑に検証しすぎたせいでmasterブランチがカオス状態という、masterにあるまじき有様です。。。なので早いところ整備して、ここに堂々とリンク貼れるくらいの状態には持っていきたいです。いずれ、このネタの構築寄りの解説を記事にする予定ですので、その時までには・・・

最後に。Excel方眼紙を割とdisる記事になりましたが、私自身はExcelが好きです・・・といっても、表計算ソフトとして。優れたソフトウェアも本来の用途で使用してこそ、だと思います。

蛇足

AWSは使えるけどSaaSサービスの社内利用が市民権を得ていない、そんな方のために。

今回紹介した構成は、CIツールやDockerレジストリに外部サービス(CircleCI, Docker Hub)を利用しています。私にとってはそれが一番構築しやすかったから...というのが理由ですが、実際の案件では外部サービス利用にハードルがあるかも知れません。

構成図（代替案）

DockerレジストリやCIの構成要素はAWSサービスで代替することが可能です。その場合の代替構成は下図のようになります。

この構成ではDockerレジストリの代替をECR(Elastic Container Registory)が、CircleCIの代替をCodeBuildが担うことになります。GitHubもAWS CodeCommitで代替可能(※)ですので、フルAWSな構成図も作れます。

p style="display: block;">※CodeCommitのリリース当初はプルリクが使えませんでしたが、2018年3月時点では利用可能になっています。

運用手順書の運用をカイゼンする - Excel方眼紙は卒業できるのか -

はじめに

概要

構成図

問題提起