はじめに
ソフトウェアの開発は厳しい工数管理と納期に迫られます。その中でドキュメントはしばしば削減対象となります。ただ、ドキュメントを削減したツケは運用保守フェーズで払うことになります。コードを見ればわかる？サーバ構成なんて調べればわかる？問い合わせや障害の調査時に訳も分からずコードとサーバをひっかきまわしながら同じことを言えますか？
今回のエントリでは運用保守の担当としてこんなドキュメントがほしかった・あってよかった…という一覧をまとめました。
なお、今回のエントリはまだまだ改善の余地があると考えています。今後の自身の経験や周囲の意見などを取り入れながら、継続的に改善できればと考えています。
ドキュメントは何のために必要か？
まず、運用保守に限らず、ドキュメント全般について考えてみたいと思います。
ドキュメントはコミュニケーション手段の一つだと考えています。プロジェクトに関わる全ての方がコードを読めるわけではありません。同時に、全員が業務や要件を詳細に把握しているとは限りません。お互いが理解しあい、議論するための共通言語としてドキュメントがあると考えています。共通言語としてモデルを挙げる場合がありますが、今回はドキュメントに含めています。
また、コードは完全で具体的です。それゆえ理解するまでに時間と労力が必要です。これを適切に抽象化してドキュメントに落とし込むことで理解しやすくなります。
よって、この2点にそぐわないドキュメントは不要かもしれません。例えば、特定のチームでのみ利用している小さいコードであったり、コードをそのまま日本語に変換したような詳細な設計書は不要という判断もありだと考えています。
運用ドキュメントの在り方
Internet Week 2011で発表された『運用ドキュメントのあり方と課題』と題したプレゼン資料が公開されています。
https://www.nic.ad.jp/ja/materials/iw/2011/proceedings/t3/t3-01.pdf
この中でドキュメントは「資産性ドキュメント」と「費用性ドキュメント」に分かれるとしています。
- 資産性ドキュメント
- 反復利用・部品再利用性の高いドキュメント
- 変更差分の継続更新により陳腐化回避を実現しているドキュメント
- 費用性ドキュメント
- 反復利用、部品再利用性の低いドキュメント
- 差分更新の効果が低く、作成直後をピークに以後陳腐化していく ドキュメント
そして、費用性ドキュメントに割く時間を減らし、資産性ドキュメントに割く時間を増やすべきと主張しています。
今回のエントリで取り上げるドキュメントは資産性ドキュメント中心ですが、費用性ドキュメントでも効果があったものは追加しています。
この後の節で、このプレゼン資料で取り上げられた「3つの根幹」を参考にドキュメントの必要性を説明しています。
| [Why] |
なぜ書くのか？ |
| [Worth] |
書く価値は何か？ |
| [What] |
何を書くのか？ |
運用ドキュメントの管理
保存先
ドキュメントの保存先は会社の規定に従う必要があります。もし決められていないのであれば、以下の観点で考えるのが良いと思います。
- 案件やフェーズ単位で階層を設定できること
- ドキュメントへのアクセスを制御できること
- 定期的にバックアップされていること
- ドキュメント更新の記録が残ること
- 会社のポリシー(ISMSなど)に反しないこと
これらを満たして比較的使い勝手が良いのはバージョン管理システム(例：Git, Subversion)、ファイルサーバ、Wikiなどでしょう。
例えメンバーがアクセス可能であっても、個人用フォルダに格納することは避けましょう。個人用フォルダは退職と同時にアクセス権が削除され、二度と取り出せなくなる恐れがあります。
また、ドキュメントに使った図や表のファイルも同じところに保存しましょう。一緒に保存しないと、後から改訂しようとしたときに苦労することになります。
ファイル形式
ファイル形式は他の方も閲覧および編集可能なものを選ぶ必要があります。
例えば、Microsoft Project や Microsoft Visio はライセンス数に制限があるかもしれません。個人で導入したソフトウェアの独自フォーマットだと、他の方がそのソフトウェアを導入できなかったり、拡張子だけでは何のソフトウェアのファイルかわからず、閲覧すらままならないかもしれません。
差分の扱い
既存のソフトウェアを改修すると、以前との差分が生まれます。これをドキュメントで管理するためには2つの方法があります。
- 常に最新の仕様をまとめたマスタドキュメントを作成・維持する
- マスタドキュメントを確認すれば最新の仕様を把握できる
- 全体を理解しやすい
- 将来のリリースで含める予定の仕様を記載できる
- 前回リリースからの差分情報をまとめたドキュメントを作成する
- 特定のリリースに関する差分（追加・変更・削除）が把握しやすい
どちらの方法も一長一短ですが、定期的にマスタドキュメントをアップデートすることをお勧めします。保守期間が長くなるにつれて差分が増えること、また差分情報の積み上げだと差分に対して差分を適用することもあり、最新の仕様を正しく把握することが困難になるからです。
この議論に関しては「要求開発と要求管理」の『第20章 複数リリースの要求』を参照ください。
改定来歴をつける
ドキュメントがファイルの場合、例えバージョン管理システム(VCS)で管理していても改定来歴を付けたほうが良いです。
改定来歴はVCSのコミットコメントで代わりになるという意見がありますが、ファイルはVCSからチェックアウトして外部に渡されたり印刷されたりします。そうすると、ファイルに改定来歴がないとコピーもしくは印刷を受け取った側では改定内容がわからなくなります。
書き手としてはかなり手間ではありますが、読み手のことも配慮して改定来歴は記載すべきです。
どのドキュメントから作るべきか？
この後のドキュメントリストで挙げたものは一通り用意することをお勧めしますが、限られた時間の中で一度にそろえることは難しいと思います。リストを優先度の順に並べました。現状を鑑みて、取捨選択及び優先度の変更を行っていただければと思います。
ドキュメントの構成は一例であり、追加・削除・変更したり、まとめたり分冊したりと管理しやすく使いやすいようカスタマイズしていただければと思います。
今回挙げたリストは運用保守で日常の業務をこなすために最低限必要と思われるものです。今後の開発・保守のため、資産性ドキュメントという観点でさらに拡充することをお勧めします。
運用保守で求められるドキュメントリスト
ドキュメント一覧
[Why]
ドキュメント群は開発や保守を重ねるうちにしばしば様々な場所へ散在していきます。また、複数のシステムにまたがる資料は共通のパス（プロジェクトのドキュメント群とは離れている）に格納されることがあります。こうしたドキュメント群がどこにあるかを示す地図のようなドキュメントが必要となります。
[Worth]
必要とするドキュメントがどこにあるのか、またその詳細を知ることができる。
[What]
- ドキュメント名
- ドキュメントパス
- ドキュメントの説明
- 管理部署（作成もしくは更新を担当する部署）
- 更新タイミング
ドキュメント群があまりに散在しているのであれば、ある程度整理してから一覧を作ったほうが良いでしょう。
個々のドキュメントを全てリストアップするのは作成も更新も大変なので、グルーピングしてもよいかもしれません。例えば、画面毎に設計書を作成した場合、それを一箇所にまとめて「画面設計書」とグルーピングできます。
[Why]
障害や改修のための調査ではその対象が明確となっている必要があります。そのために、対象のシステムがどのソースコード・モジュールから構成されているのか、前回からの差分は何だったのかを把握することが必要となります。
[Worth]
ソースコードの場所や管理方針、ビルド方法、モジュール管理の方法を知ることができる。
[What]
- バージョン管理ツール
- ソースコードのリポジトリ（パス）
- ソースコードの管理方針
- コミットのルール（コメントのフォーマットなど）
- ブランチのルール（ブランチに持たせる役割、ネーミング、 作成・マージ・削除のタイミングなど）
- タグのルール（ネーミング、作成のタイミングなど）
- ビルド／デプロイ
- 実行のタイミング（自動／手動）
- 実行手順
- デプロイ環境（テスト・本番）による違いも明記すること。
- （自動化している場合）処理概要
- 処理の概要を記載することで、自動化によるブラックボックス化を避ける。
- ビルドモジュールはどこのサーバのどのディレクトリに出力されるのか。
- ビルドモジュールはどのサーバを経由してデプロイ対象サーバにデプロイされるのか。
- デプロイ後、自動的に再起動されるのか。それとも追加操作が必要か。
- モジュールの場所
- デプロイ先のサーバ及びパス
- クラウドストレージやファイルサーバからモジュールを自動的にダウンロード＆デプロイするような場合はそのパスも記載する。
- モジュールのコピーの保管場所
- Mavenのようなライブラリ管理ツールを使っている場合は社内リポジトリも対象となる。
ローカル開発環境構築手順
[Why]
開発を行うためにはまず開発環境の構築を行います。例えば、IDEのような開発ツールのセットアップが必要となります。
開発環境のセットアップではしばしばエラーに悩まされます。さらに、メンバー間の環境の違いによる不具合が発生することもあります。こうした不具合や試行錯誤を減らすために、統一したセットアップ手順をまとめておくことが重要です。
[Worth]
メンバー間で統一した環境構築を行うことができる。また、構築時に起こるエラーへの対処をノウハウとして蓄積・共有できる。
[What]
- 利用する開発ツールの名称
- 開発ツールの入手方法
- ライセンス管理
- 開発ツールのインストール方法
- 可能な限りインストールパスも統一したほうがエラーを回避しやすい。
- 開発ツールの設定方法
- 設定をファイルでエクスポート／インポートできればより望ましい。
- 構築時のトラブルシューティング
[Why]
優秀なアーキテクトが素晴らしいアーキテクチャを構築したとしても、アーキテクト及び共に開発に携わったメンバーはリリースが終われば次の仕事へ向かうでしょう。アーキテクチャの意図をその後のメンバーに正しく引き継ぎために必要となります。
[Worth]
アーキテクチャの意図をメンバーに正しく伝えることができる。
[What]
- システム（モジュール）の目的
- 本システムの責務（何を処理するのか？）
- 外部システムへの依存（何を任せるのか？）
- システム構成
- コードの構造（コメントに代えてよい）
- ネーミングルール
- パッケージと用途
- 主要なクラスと用途
- サンプルコード
稼働環境構成
[Why]
本番稼働後も不具合や脆弱性対応のため、継続的なアップデートやパッチの適用が必要となります。こうした調査のために現状を把握できるドキュメントが必要となります。
また、アプリチーム、インフラチームのように縦割りの組織となっているとき、このドキュメントがチーム間の橋渡し役となります。
[Worth]
不具合や脆弱性対応の調査を行う際の基礎資料となる。また、同様のシステムを新たに構築する際にも参照できる。
[What]
本番環境とテスト環境で差異があれば、それぞれについてまとめておくことが必要です。
- マシンの用途
- マシンのスペック
- マシン毎の構成（各項目毎に名称、バージョン（パッチ）、設定内容）
- OS
- アプリケーションサーバ
- アプリケーション
- 保守運用対象のアプリケーションは頻繁にバージョンアップすることがあるため、独立して管理してもよい。
- ライブラリ
- 運用ツール
- アカウントと権限
- ネットワーク構成
- 少なくとも外部システムとの接続までは記載する。さらにその先についても記載があると障害時に役立つ。
- ファイアウォールの設定
- 特に開発の都合などで一時的に開けた場合は依頼者（連絡先）、意図、期限を必ず残す。
- マシンへの接続方法
- アカウント
- 踏み台サーバ
- ネットワークの制限
- プロトコルの制限
- ログの出力先
- 転送・削除・圧縮などが行われる場合はその条件と実施内容。
[Why]
ジョブは一度作られるとアップデートされる機会が少なく、また普段はひっそりと稼働していることが多いです。そのため存在を忘れられがちですが、時間の経過とともに担当者が入れ替わり、把握できなくなるケースがあります。また、作業のために一時的に作られたスクリプトが放置されたまま残され、削除してよいのか判断できないこともあります。
こうした状況を避けるためにもジョブ（スクリプト）一覧をまとめ、用途や起動タイミングなどをまとめておきます。
[Worth]
システムで稼働しているジョブの内容、実行タイミングなどを把握できる。
[What]
- ジョブ（スクリプト）名
- 処理内容
- 実行のインプット／アウトプット
- パスと引数
- 起動（実行）タイミング
- ジョブ実行失敗時の影響と対応
- 担当部署
連絡先一覧
[Why]
システムを引き継いだ時に困ることの一つに、誰に相談すればよいかがわからないことです。一覧表があることでその懸念が緩和されます。
ステークホルダー・リストもこの一覧に含まれるでしょう。
[Worth]
相談相手とその連絡方法がわかる。引き継ぎ時に顔合わせすべき相手が明確になる。
[What]
- 担当（システムもしくは役割）
- 会社名・所属
- 氏名
- 電話番号
- メールアドレス
- 連絡時の決まり事
運用保守プロセス（フロー）
[Why]
会社として開発プロセスが規定されていても、運用保守でありがちな小規模な改修や緊急対応にはフィットしないことがあります。
本来は会社レベルで規定すべきものですが、無い場合はチーム内で定義することで、都度悩むことなく、取り組むべき課題に集中できるようになります。
[Worth]
プロセスがあることでやるべきことが明確になる。
[What]
- プロセス全体のフロー図
- 課題の受付
- チームへの改善・改良・障害調査の依頼ルール
- チーム側受付担当者
- 課題管理
- 利用するツール
- 課題のテンプレート
- 課題の分類
- ステータス変更の基準
- 進捗の基準
- ドキュメント
- 既存の更新対象ドキュメント
- 課題に応じて作成するドキュメント
- テスト管理
- リリース判定基準
- リリース
- リリース標準手順
- 切り戻し標準手順
- 障害発生時報告フロー
画面設計書
[Why]
動くアプリケーションとそのソースコードがあっても、その全体像や処理内容を正確につかむことは困難です。また、今後の改修の中で新たな画面を追加する際、既存画面の構成や遷移を度々参照することになります。
ただし、ごく小規模のシステム（画面）や処理内容であれば不要という判断をしてもよいかもしれません。
[Worth]
画面の構成と挙動を正しく把握できる。
[What]
- 画面一覧
- 画面フロー（遷移図）
- ユースケース
- 画面項目
- データ取得元(Input)
- 表示処理
- 表示内容(Output)
メンバー受入レクチャー資料
[Why]
運用保守が長く続くにつれ、メンバーの入れ替わりが発生します。新規メンバーに対し、業務知識やシステム、これまでの背景などを伝えることで、よりスムーズに参画しやすくなります。
[Worth]
新規メンバーに対して、資料を基に体系立てたレクチャーを行うことができ、より早く戦力となってもらえる。
[What]
本エントリで挙げたドキュメント群はレクチャーにも利用可能です。レクチャーに利用することで拡充すべき内容が見つかることもあるでしょう。
そのうえで、補足として以下の情報をまとめておくとよいでしょう。
- 業務に関する基礎知識
- 業務知識を自己学習に頼らざるを得ない場合でも基礎知識があれば学習しやすくなります。
- システムの目的・背景
- これまでの経緯
- 組織図・体制図
- まず確認すべきドキュメント群
ミーティング資料・議事録
[Why]
運用保守フェーズは開発フェーズの時よりもカジュアルな形式の打ち合わせとなることが多いです。ですが、そこでの決定事項は今後にも影響することであり、開発フェーズ同様に議論の過程を記録に残す重要性は変わりません。
[Worth]
ミーティング内容を後で振り返ることができる。参加できなかったメンバーが参照できる。過去の経緯を調べることができる。
[What]
- ミーティング資料
- 議事録
- ホワイトボードの記録（画像）
まとめ
運用保守フェーズからプロジェクトに参加したが、ドキュメントが何もないことに愕然とした…。そんな経験をされてきた方もいると思います。そして、いつしか自分もその状況に慣れて、仕方ないよと自分にもメンバーにも言い訳をしてしまうかもしれません。
ですが、「ドキュメントがない」という現状を知った時こそ、ドキュメントを整備するためにどうすればよいかを考えるべきだと思うのです。一から作ることは大変です。でも、きっと何もないことはなく、散在していたり古いまま放置されているドキュメント群があるはずです。もしかしたらメモであったり、メールとして存在しているかもしれません。まずはそれらを集めること。そして、そこから使えるものを取捨選択し、最新の状態に磨き上げてはいかがでしょうか。同時に、使えないドキュメントはきっぱり捨てるべきです。
例えそのソフトウェアのライフサイクルが尽きたとしても、資産価値のあるドキュメントは別のプロジェクトのお手本となるでしょう。
参考
本エントリでは『第20章 複数リリースの要求』を紹介しました。これ以外にも保守開発での要求を適切にとりまとめるための参考となります。
