記載目的
先日チームメンバより『リソース構築手順書』の作成・レビューで何に気をつけてるのか質問されました。
改めて今まで自己流で手順書の作成・レビューをしてしまっていたなと思い、まずは現状自身が気を付けてる観点を言語化してみようと思います。
それと弊チームは『Excel手順書』大好きチームなので、IaCでコード管理して云々のようなことに関しての記載はございません。
『リソース構築手順書』を作成する場合に気を付けてること
個人的には『プロジェクトの背景と目的の理解』が重要で、背景をしらないでつくられたものと、背景ありきでつくられたもののの精度に大きく関係していると考えている。
プロジェクトの背景と目的の理解:
- 新機能の実装にあたりプロジェクトの背景や目的を理解するため、依頼者との会話や関連ドキュメントを確認して、『リソース構築手順書』フェイズに至る前段を把握する。
成果物の確認:
- レビュアーや作業者との視点を合わせるために目的や手順書の粒度について事前の会話を実施する。
- 最も重要なポイント（クリティカルポイント）を共有し、確認するべき事項を明確にしてメンバー間で周知する。
用語の統一と説明:
- 専門用語や略語を使用する場合は、それらを一貫して使用し必要に応じて用語の定義や説明を記載する。
フローの確立:
- 手順書は既に確立されたフローに基づいて作成されていること（例えば、検証環境での事前確認など）。
網羅性:
- 手順書のページ前に全体の構築フローを記載することで、本構築における全量が把握出来るようなページを作成する。
詳細な手順の記述:
- 構築対象のリソース名(プロジェクトの命名規則確認)や具体的な構築手順を記載する。
- 作業者の経験レベルによっては、必要に応じて画面キャプチャを取り入れる。
※基本的に手順書作成者と実際のリソース構築者は同じものとする。
終了・成功条件の記載：
- 1つの作業につき、1つの終了・成功条件を記載する。
『リソース構築手順書』をレビューする場合に気を付けてること
当然かもしれないが『フローの実用性』が重要で、そもそもリソースの構築がされないと話しにならない。
その上で構築されたリソースが他のリソースへの影響を考える必要があると思っている。
フローの実用性:
- 作成された手順書に沿ってサービスが構築できるかを確認する。不明瞭な点があれば実際に手順を試行及び、関連するブログや文献を参照する。
既存運用への影響：
- リソースが構築されることによる、運用されている他リソースへの影響を想像する。
(例)Lambda実行に伴うマネージドで構築される、CloudWatchLogsのログ・監視の設定
通信要件のチェック:
- 特に問題の起きるセキュリティグループ（SG）やネットワークACL（NACL）の部分に注意、通信要件をチェックする。
命名規則の確認
- 用語やリソースの命名が一貫性を持ち、明確であるかを確認する。
用語については作成者が定めたものなのか、AWSのものなのか、PJ独自のものなのかのを明瞭にする。
読みやすさ視認性:
- 文書の構成、フォーマット、語尾の揺れ、言語の明瞭さ、について評価する。
さいごに
大変属人性高めだったので、改めて文章にできてよかったです。
より精度を上げるために、AWSのベストプラクティスや、IPA（情報処理推進機構）のセキュリティガイドラインなども読んで、また来年からの『構築手順書』作成・レビューをしていきたいと思います。
他にもコレ読んでいたほうがいいなどありましたら教えてください。