記事起こしの背景
私は運用保守プロジェクトを担当している。一方
- (前後の経緯は割愛するが)ドキュメントとマニュアルがほぼ無い状態
- その為、記憶頼み・極端な属人化がプロジェクトで常態化
- 特に記憶頼みの仕事はミスを誘発している
で困っている。
- 問題意識はあるが、何から手を打つべきか分からない
- なので、まずは「何が揃っているべきか」を把握したい
の考えから掲題の下調べをした。
留意事項
後述の一覧は、参考文献(記事末尾より)を @ymatsukawa が解釈、意訳および現場向けに編集したものである。
2019/5 現在 Kindle Unlimited にて 0 円のため、余裕のある方は購入にて内容を確認されたい。
本題
プロジェクトで用意しておくドキュメントとマニュアル一覧
* 市場向けドキュメント
* 広告
* よくあるお問い合わせ(FAQs)
* 操作マニュアル
* リリースノート
* 障害レポート
* 企画書
* 市場戦略を記載したドキュメント
* 要求書
* 四半期 - 通期の要求一覧
* プロジェクト遂行ドキュメント
* 要件一覧
* プロジェクト計画
* テスト計画
* テストスクリプト・テスト実行方法
* 技術仕様
* テストケース
* 方針・手順書(ポリシー・マニュアル)
* 基本操作手順書
* 機器の運用方針・手順書
* テスト方針・手順書
* 開発方針・手順書
* デプロイおよびリリース方針・手順書
* 作業ワークフロー・作業指示書
* 導入教材
* いわゆる引継用のドキュメント
各項目について、筆者なりの解説
筆者 = @ymatsukawa
市場向けドキュメント
主に市場・顧客向けドキュメント。公式 Web ページ、ヘルプページなど公然に載せるもの。
内部組織向けにも「いつ何が起きたか」等を知る道具として使える。
* 広告
* よくあるお問い合わせ(FAQs)
* 操作マニュアル
* リリースノート
* 障害レポート
企画書
そう堅いものでなくても、例えば企画部・マーケティング部のメモ書きでも良い。
「市場動向解析より xxx の必要性が見られる。四半期中には yyy を市場投入し、その妥当性を確証取ってみたい」
といった感じのもの。これを参照できる事で「なぜそれをやるか」を把握できる。
要求書
企画を基に要求を一覧化したもの。これから何をしていくか、いきたいかが記載されている。
「... を実現したい」という要求レベルであって、要件ではない。
要件は要求を漏れ分なく条件と制約で細分化したものである。
「... を実現したいという要求に対し、X という機能を設ける。X という機能は Y, Z というタイミングで実行され...」
という感じである。
プロジェクト遂行ドキュメント
管理者・開発者・運用者がプロジェクトを 1 から 10 まで遂行する為に必要なもの。
* 要件一覧
* プロジェクト計画
* テスト計画
* テストスクリプト・テスト実行方法
* 技術仕様
* テストケース
- 要件一覧にて、要求がどのように要件へ落とし込まれているか
- プロジェクト計画にて、要件はどのようにスケジュールされているか
- 要件を達成する為に、テスト計画は建てられているか
- テスト計画を完了する為に、テスト実行方法は書かれているか
- テスト実行時に必要な、技術仕様とテストケースは書かれているか
方針・手順書(ポリシー・マニュアル)
管理者・開発者・運用者がプロジェクトをミスなく実施する為に必要なもの。
* 基本操作手順書
* 機器の運用方針・手順書
* テスト方針・手順書
* 開発方針・手順書
* デプロイおよびリリース方針・手順書
* 作業ワークフロー・作業指示書
基本操作手順書
ステージング環境、場合によってはリリース後の本番環境にて動作確認時に用いる。
機器の運用方針・手順書
開発機器であればネットワーク環境構築手順書(例. プロキシネットワーク)、
開発ツール以外で導入必須なソフトウェア(例. セキュリティソフト)の導入手順書など。
ステージング環境や本番環境であれば、メンテナンス時間やアクセス権限方針など。
テスト方針・手順書
テスト実施時のハードウェア、OS、付属機器、バージョン、選定されたテストケースを示した方針、および実施手順書。
テスト方針は「何を以ってテストとするかの決め」であり
テスト計画は人員配分、日程調整といった「どのようにテストを進めていくかの決め」である。
開発方針・手順書
環境構築方法、OSや開発用端末の制約方針、OSS 導入方針および静的解析ツールの導入手順など。
デプロイおよびリリース方針・手順書
ステージング環境および本番環境へのアクセス権限方針およびデプロイ・リリース手順。
ロールバック方針やアップデート方針も同様。
作業ワークフローおよび作業指示書
「誰が、いつまでに、誰に対して、何をどのような手順で実施すべきか」が示されたもの。
導入教材
引継時に手渡しできるもの。プロジェクトの全容を把握できる。
(ここまで挙げたドキュメント・マニュアルがリンクされていればよいかもしれない)
終わりに、その他
一覧は完全ではないと考えているので、各々の手元で適宜肉付けお願いします。
特に「技術仕様とは何なのか具体的に」への筆者回答は未回答とします。
書籍などを漁っていますが、考えがまとまっていないからです。
参考文献
-
Morgan, Kieran. Technical Writing Process: The simple, five-step guide that anyone can use to create technical documents such as user guides, manuals, and procedures . Better On Paper Publications. Kindle 版.
- Chapter 1 - The Technical Writing Process
- What type of documents do technical writers write?
- Table 1: Types of documents written by technical writers