手順書を作成する上で意識していること

[パーソンリンク アドベントカレンダー](https://qiita.com/advent-calendar/2021/personlink) 23日目です！🎉

## はじめに
チームで作業する上で、認識を合わせることはとても重要です。特に開発規模が大きくなるにつれ、参画する人数も増えることで、作業の仕方や視点がバラつき、工数や品質に大きく影響を与えます。
そこで作業に取り組む際に重要になるのが手順書です。手順書にも様々な目的（運用手順書や環境構築手順書など）により記載項目は異なりますが、私なりに作成する上で意識している点をまとめ、サンプルを作ってみようと思います。
今回はシステムのリリース手順書を想定して作成します。

## 手順書を作成する上で意識すること
1.  手順書を利用する対象者（作業者）を設定する
    - 例えば、AWS EC2をコンソールから操作できる者など、利用者の前提条件として記載があると、手順書の作成側としても必要以上な記載を省くことができ、見やすさも上がります。
2.  読み手の理解や認識に齟齬が発生しない書き方であること
    - 設定した対象者であれば、誰でも詰まること無く手順を再現できることです。手順の内容に曖昧さや想定以外の操作の可能性を払拭するように記載します。
    - 対象者がベテランであるから、単純に項目や言葉を省略することは危険です。客観的に立って、正しい用語で説明しましょう。
3.  作業の目的を示し、手順を説明する
    - 作業目的を理解していない場合、想定外の事象が発生した際に対応できないため、目的を示しましょう。
4.  操作→確認がセットであること
    - 操作後に想定した結果になっていることを確認する手順を記載します。

## 【注意事項】
**下記の手順書サンプルに記載の内容（コマンドや説明など）はあくまで例のため、実行しないで下さい。**

## 解説
```
XXXサービス　本番リリース手順書
																		
【作成者】																		
株式会社XXXX　山田XX　

【作成日】
2021年12月1日

【改訂履歴】
版：1.1
改訂日付：2021/12/23
改訂内容：XXXX時のコマンドを追加
```
手順書名と作成者、作成日付を記載します。
手順書に版（バージョン）の記載があると改訂履歴が分かり、現在のドキュメントに至った経緯が理解できます。        

```
【手順書の概要】																					
本番リリースを行うための手順書である。																				
リリースのための作業概要を以下に明記する。																				
  EC2：新規開発したソースコードをデプロイする。																			
  DB：追加のテーブルの作成、データの追加を行う。
```

手順書の概要を端的に説明しています。
どのような作業工程があるのかを簡単に明記します。

```
【作業前提条件】																					
手順書を実行するにあたり、手順書のレビューが完了していること。																				
実行者の端末からAWS EC2インスタンスへSSH接続が可能であること。																				
12/1 12時30分にサービスが停止できる状態であること。（関係各所への連絡・合意が取れていること）
```
この手順書で作業を行う前提となる条件を記載しています。
手順書がレビュー済みかも大事ですが、作業を行う上で顧客と調整が必要なことがあれば明記したほうが良いです。

```
【作業完了条件】																					
本番リリース手順の操作が全て完了し、動作に問題が無いこと。																				
確認者から完了の確認が取れていること。
```
この手順書を通して行う作業のゴールです。
顧客と連携して行う場合、完了条件は合意を取っておく必要があると思います。

```  
【作業者】																					
Aさん（担当：EC2）																				
Bさん（担当：DB、動作テスト）																				
Cさん（担当：作業確認）

【予定作業時間】																					
2021/12/1 13:00〜14:30
```
作業者と担当する工程を記載しています。
作業の予定時間は明記しましょう。
　　　　　　

```
【連絡・留意事項】																					
作業完了後、Xさんに完了報告をすること。																				
手順操作を実施中に意図しない事象が発生した場合は、Xさんに報告すること。下記の内容を報告すること。																	
  ①発生している事象内容																		
  ②現状判明している影響範囲																		
  ③解決までの作業時間（分かる範囲で）
```
完了報告先や想定外の事象が発生した際の対応方法を記載しています。
手順書通りに上手くいかないこともありますので、その際の対応が想定されていると安心できます。
　　　　　　

```
【作業手順】																					
EC2（作業時間：30分）
```
項目ごとに大まかな作業予定時間があると作業ボリュームが想定しやすいです。

```
本番環境にアクセスし、サービスを停止する
```
作業目的を記載しています。工程ごとに目的を示し、作業者が理解して操作を行えるようにするためです。

```
 1. コマンドをターミナルに入力し、EC2インスタンスにアクセスする。																		
   ssh -i xxx.pem [ec2-user@ec2-xxx-xxx-xxx-xxx.ap-northeast-1.compute.amazonaws.com](mailto:ec2-user@ec2-xxx-xxx-xxx-xxx.ap-northeast-1.compute.amazonaws.com)																	
 2.インスタンスへアクセス後、'/home/ec2-user/work'ディレクトリに移動する。																	
 3.実行中のサービスプロセスを確認し、停止する。																		
  $ [プロセスの確認コマンド]																	
  $ [プロセスの停止コマンド]																	
 4. 以下コマンドを入力し、"＊＊＊ service stop"が表示され、正しくプロセスが停止されていることを確認する。			
  $ [プロセスの確認コマンド]																	

ファイルをデプロイする																			
 5. （・・・続く）
```
作業手順は、できるだけ**1つのアクションごと**に記載します。複数の操作を一行で説明すると分かりづらく、操作内容が複雑になってしまうからです。
また、操作を行った後は必ず確認するプロセスを挟みます。操作と確認はセットで一つ一つ丁寧に行うようにします。確認無しに進めては、正しく操作が行えているのか判断ができませんので、必ず確認するプロセスを記載します。

```
DB（作業時間：20分）
本番環境にアクセスし、データベースのバックアップを作成する
 1.コマンドをターミナルに入力し、EC2インスタンスにアクセスする。
   ssh -i xxx.pem ec2-user@ec2-xxx-xxx-xxx-xxx.ap-northeast-1.compute.amazonaws.com
 2.データベースのバックアップを作成する。
   ①dumpファイルを保存するため'/home/ec2-user/work/dump'以下にフォルダを作成する。
     フォルダ名は「db_back_{作業日の日付}」とし、下記の構成になっていることを確認する。
	/home/ec2-user/work/dump/db_back_20211013
   ②①で作成したディレクトリに移動し、dumpファイルの生成コマンドを実行する。
	mysqldump -h xxxxxxx
   ③①で作成したディレクトリに生成したdumpファイルがあることを確認し、下記の内容を確認する。
	a前回のdumpファイルと差分を比較する。
	b現在のテーブル情報、データが正しく含まれていることを確認する。
	新規テーブルを作成する
 3. （・・・続く）
```
こちらも上記と同様に操作と確認をセットで記載します。
可能であれば操作で使用するコマンドは、コピペで実行できる状態にしておくと便利です。ただし、IDやパスワードなどの重要な情報は別で管理するようにします。管理方法にもよりますが、手順書にパスワードを記載するのは避けるようにしましょう。
その際は、必ず確認先（担当者など）や参照先を明記し、作業が止まることがないように連携を取るようにしましょう。

```
動作テスト（作業時間：1時間）
 1.本番環境で、サービスに接続し、動作テストを実施する。実施項目は以下の通りとする。
  ①サービスにアクセスし、画面の表示崩れが無いことを確認する。
  ②（・・・続く）
 2. 1番の手順で問題が無い場合、Xさんに完了報告を行う。
```
最後に完了条件を満たすためのプロセスを記載し、作業を完了するようにします。

## さいごに
手順書は組織やプロジェクトにより様々なテンプレートや規則があり、これが正しいというものはありません。目的としては、どの作業者が操作しても同じ結果に辿り着くことで、そのために作業者の認識齟齬をなくすことが手順書の重要な役割だと思います。
手順書を皆で育て、分かりやすく使いやすい手順書を目指していきたいです。

最後まで読んでいただき、ありがとうございました。