はじめに

Organization設定ありでQiitaに投稿するのが初めてです。頑張って書いたので読んでください
今回は自分の2022年を締めくくる記事ということで今年意識してみたプログラミング以外で開発に役立ったことをまとめました。プログラミング関連は他の方も書いてくださってるのであえて逆張りでプログラミング以外に焦点を当ててみます。

「具体例」や「やったことで得られた効果」も共有していきます。ということでよろしくお願いします

1.手順のテンプレ化

具体例

1-1.リリース手順書のテンプレ化

Q. これなんだかわかりますか？(一部抜粋したものです)
A. リリース手順書です

事前準備
実作業(デプロイ1)
実作業(デプロイ2)
実作業(デプロイ3)
実作業(デプロイ4)
リリース後不具合発生時、元のバージョンに戻す方法(APIサーバー)
リリース後不具合発生時、元のバージョンに戻す方法(フロントエンド)
リリース後不具合発生時、元のバージョンに戻す方法(DB)

で構成されてます。

Amazon Web Serviceを使う場面ではどの画面で行うのかURLまで記述してあります。また、コマンドを打つときは 1.どこのディレクトリで 2.どのコマンドをまで記述してあります。
※手順書の質を高めるためにはコマンドの実行結果を控えておくと良いです。コマンドの結果が予想と離れていることを確認できます。

※ちなみに

テンプレにない特殊作業がある場合は目立つ色で追記します

やったことによる効果

リリース準備の時間を削減

リリース手順作成自体は慣れれば5分で終わります。手順書作成後はダブルチェックをしますが、ダブルチェック込みで15分で終了することもあります。また、毎回一から作ることはないです。切羽詰まってる時でも時間を食わずに作成できます。

新しい手順が増えたときはテンプレを更新すればOKです

リリース作業のミス減少

テンプレがあるので「あれ今回はこれ入ってるっけ？」という漏れが少ないです。
また、必要のないことはグレーアウトするので今回のリリースでこれはしないというのが手順書を見ればすぐわかります。

リリース作業者の不安軽減

手順書はあります。ダブルチェックもしました。あとは慢心せず手順を行うだけ。
いつもと同じリリース作業だが、「前日に突貫で作ってチェックをしてない」よりは安心できます。

他の人でもできるようになる

これ大事
手順書があれば他の人でも担当することができます。いきなりは難しいですが、元々手順書を作成していた方が2,3回付き添えば作成は1人でできるようになります。また、元々手順書を作成していた人はダブルチェック係になることができます。

こうすればリリース準備作業を脈々と受け継ぐことができると思います。

2.作業中の記録を取る

具体例

2-1. 環境変数の追加/変更

いつ環境変数を何から何へ変更したのかがわかるように記録します
例)
実施日:2022/12/10
変更内容：変更した環境変数

	環境変数名	値
旧	NEXT_PUBLIC_HOGE	HOGE1
新	NEXT_PUBLIC_HOGE	HOGE2

変更作業を記録しておけば似た作業するときに楽できます。

※ちなみに

環境変数にシークレット系を入れる場合は情報漏洩を防止するため値自体は記録に残しません

2-2. IAM(Amazon Web Service)の変更

いつ、何を、どう変更したのかわかるよう差分を記録します

例)
実施日:2022/12/13
変更内容：追加したポリシー(json)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListAttachedRolePolicies",
                "iam:ListRoles",
+               "ec2:DescribeSecurityGroups",
+               "ec2:DescribeSubnets",
+               "ec2:DescribeVpcs",
+               "ec2:CreateSecurityGroup"
            ]
         }
     ]
}

2-3. 実装中にハマったこと/外部APIの動作

何で詰まってどうやったら解決したのかまで書いておく。

外部API関連の記録であればコード内の関連部分にリンクをコメントアウトで入れると良いです。実装中、不思議に思って質問すると「ここはね実は...」と前任者から初めて知らされることは減らせます。

sample.php

<?php
/**
 * attributesを改行で指定するとエラーになる
+* https://hogehoge.com/post/10001
 */
  $query = [
            'type_name'     => 'sample',
            'attributes'    => '["hoge1", "hoge2", "fuga1", "fuga2"]',
        ];

やったことによる効果

情報共有が楽になる

情報の共有が「これここに書いてあります！」で済みます。
口で説明いただき理解することもできますが、理解した人がまた口で別の人に伝えてまたその人が口で伝えて...となると同じことの繰り返しですし、説明する人の説明能力に依存してしまいます。

また、説明する時間もかかります。説明時間を設けたら最低でも2人の作業時間は減ります

再現性の担保

システム開発では多くの場合、ステージング環境と本番環境があります。※2つに加えてデモ環境がある場合もあります。
値は違えど同じ環境変数を設定することは多いので手順は残しておくと安心できます。

他の人でもできるようになる

これ大事
再現性の確保と似てますが、1回目にやった人が付き添いで2回目の作業は違う人にしてもらうことができます。属人化防止になります

なんで幸せになれるのか

「紹介したことを意識するとなんで後で幸せになれるのか」を自分なりに考えました

事実を残してるから

問題発生時、憶測で議論しなくても良くなります。事実を辿っていく方が原因究明を素早くすることができ、心理的負荷が減ると思っています。『あの時は...確かこうしたはずだから...』と探り探りで解決しようとして余計わけわからなくなるのは避けたい

手順書を作ればその手順通りに作業します。作業記録は実際の行いをそのまま書き残したものです。そこに残るのは 本当に行う or 本当に行った事実 です。たとえ失敗しても事実に基づいて改善ができるはずです。

「多分」とか「思い出せないなぁ」を減らそう

再現性の向上/属人化の解消

自分が経験したプロジェクトでこんな状況がありました

"特定の人がずっと作業を担当し続けて他の人はしていない。なお手順は特定の人の「頭の中」にしかない"
"普段は〇〇に所属してる人なら作業可能。でも、特定の時だけ〇〇の人ではなく△△に所属してる人じゃないと作業できない"

手順書を作ることで特定の人しか持ってない暗黙知を形式知に変えられます。また、手順書を作ることで特殊状況下でも同じ手順を踏んでもらうことを強制できます。今まで特定の人しかできなかったことを他の人もできるようにすれば属人化はなくなり、負担が分散できます。

「あの人じゃなきゃできない」、「あの人いつも忙しそう」を無くそう

最後に

今回はドキュメント作成を開発者が意識すると良いことを紹介しました。何か1つでも参考になれば幸いです。自分は今回書いたことをより精度上げれるよう、これからも精進して参ります。

終わり