asken テックブログ

askenエンジニアが日々どんなことに取り組み、どんな「学び」を得ているか、よもやま話も織り交ぜつつ綴っていきます。 皆さまにも一緒に学びを楽しんでいただけたら幸いです!

インフラチームのタスクを支えるドキュメント施策の紹介

はじめに

インフラエンジニアの鈴木です。半年ほど前にaskenに入社しました。
私が2人目のインフラエンジニアだったため、インフラでチームができたのをきっかけに、チームでの進め方を整理してきました。
今回は、インフラチームで実施している施策について紹介したいと思います。

インフラチームでのタスクには、新しい環境を構築したり、設定修正を行ったりすることがありますが、タスクを円滑に進めるための施策をチームで取り組んでいます。
施策にはドキュメント以外もありますが、今回はドキュメント関連にフォーカスします。
正直、この施策のおかげで、入社して半年程度でもスムーズに働けています。

どんなことをやっているか

インフラに限らない話ですが、あるタスクがあった場合に「検討する作業」「作る作業」がエンジニアのタスクとしてよく発生します。
タスクの中で以下を実施することでドキュメントに残り、レビューもしやすくなります。

検討する作業(インフラの場合:環境設計や調査するとき)

  • ADR作成
  • 大きな検討時はDesign Doc作成

作る作業(インフラの場合:環境構築や修正リリースをするとき)

  • 作業手順書の作成
  • リリースチェックリスト(作業ログ)の作成

ドキュメント施策の紹介

ADR

アーキテクチャ・ディシジョン・レコードの略。最近はいろんなところでADRを残そう!って使われています。アーキテクチャ(インフラだと細かいレベルの設定等の検討や決定)に関する意思決定を記載します。

ADRを作る理由は、決定内容とその決定に至った理由や過程、背景を残しておくためです。 よくあるのが「仕様を決めた後に年月が経過して、なんでこの仕様にしたんだっけ、、?」がわからなくなることです。
ADRはその仕様に至った理由が記載されているので重宝します。
(むしろその仕様に至った理由を記載しないADRはダメなやつです。私はたまに理由の記載漏れをやってしまい、レビューで指摘頂いたりします。)

以下は実際にインフラチームで使っているフォーマットです。
個人的に「代替案・ボツ案」を明確に記載する項目があるのが良いなと思っています。
代替案、ボツ案を書いておくと、なんでこっちにしなかったんだっけ、、? が後から追えます。

# 背景、目的
(この内容を検討するに至った背景、目的を記載)

# 決定事項
(この ADR で決定したい内容とその理由を詳細に記載)

# 代替案、ボツ案
(検討した他の案があれば、ボツにした理由も合わせて記載)

# 影響
(この内容を適用した場合に起こる予期される影響)
(良い影響も悪い影響も考えつく限り書く)

# 参照
(参考にした方が良い資料等があればそのリンクを貼る)


Design Doc

新規機能など大きな設計などをするときに作成します。 ADRは1つの意思決定について書きますが、Design Docは全体を俯瞰するドキュメントをaskenでは記載しています。○○機能の環境設計などですね。 (ADRとDesign Docの使い分けは、会社やチームで異なるので、自分のチームはこうする!を決めるのが良いと思います。)

実際に使っているフォーマットです。背景、設計したい内容の詳細、懸念事項などを書きます。

# 著者
(このドキュメントを管理している人を書く)
(更新に携わった場合はその人の名前も追記する)

# ゴール
(このドキュメントのゴール(目的)を記載する)
(このドキュメントを読み終えた時に期待する状態等を記載)

## ノンゴール
(このドキュメントに書かないこと、取り扱わないこと、期待しないこと等を書く)

# 背景
(このドキュメントを用意するに至った背景や課題を書く)

# 概要
(この Design Doc の概要を書く)

# 詳細
(この Design Doc の詳細な内容を書く)

# 注意点
(この Design Doc の注意点を書く)

# 代替案、ボツ案
(この Design Doc を書くにあたって検討された別の案と、それがなぜ採用されなかったのかを書く)

# プライバシーに関する懸念事項
(個人情報等のプライバシーに関する懸念事項を書く)

# セキュリティに関する懸念事項
(セキュリティ的な懸念事項を書く)

# 参照
(他に参照するべき資料がある場合にリンクを貼る)
(内部のリンクでも良いし、外部のリンクでも良い)

Design Docを書く上で私が気に入っている項目が2つあります。

  • ゴールとノンゴール
    • ゴールには、このドキュメントは誰を対象にしているのか、読んでもらったら何を理解して欲しいのかを書きます。
    • ノンゴールには、このドキュメントでは書かないことを明確化します。こちらを書くことで、記載時にも何を書いておけばいいのか明確になります。
  • 代替案・ボツ案
    • ADRでもあったので、またか。。みたいな感じですが、「代替案・ボツ案」はDesign Docでも活躍します。
      • 大きな設計をするときによくやるのが、複数案出す→比較検討する→その中のベストな案を選択する、という流れです。
      • あとでドキュメントを見ると、設計内容と検討結果が同じところにないということがよく発生します。
        • 結局なんでこの方式にしたんだ、、、が決めた人がもういなくなってわからないやつです。。。
      • Design Docに「代替案・ボツ案」を書いておくことで、この現象を防げるのでお薦めです。

→この2つが設計資料などに書いてないことが多いので、できるだけ書くようにしています。

作業手順書

よくあるやつです。
インフラだとTerraformなどのIaCでリソース管理するか、手動で構築を実施するので、それらの手順を記載しています。
書くことを必須にすること、レビューすることが大事と思ってます。
フォーマットはこんな感じです。切り戻しの手順も必ず書くことがポイントです。
バックエンドでもDBカラム変更などがあれば書いたほうが良いです。

# 背景、目的
(この作業を行う背景と目的を記載)
(ADR 等、既に背景や目的が記載されている別のドキュメントがある場合、そこへのリンクでも OK)

# 事前準備
(この作業を行う前に実施しておく事があれば記載)
(特に無ければ未記載でOK)

# 作業手順
(本番を想定した作業手順を記載)

# 動作確認
(変更後の正常性を確認する方法を記載)

# 切り戻し

## 判断ポイント
(切り戻しを実施する判断基準を記載)

## 手順
(本番を想定した切り戻し手順を記載)


リリースチェックリスト(作業ログ)

作業手順とセットで作成するチェックリストです。
チェックリストと聞くと、どうにも堅苦しいイメージがありますが、自分の作業漏れをチェックして、作業ログとして残しておくものなので、リリース時は書いた方が良いです。

フォーマットはこんな感じです。リリース毎に各項目が出来てるかチェックします。
各項目を見ると必要!となるんですが、チェックしないとおざなりになるやつだと思ってます。

# チェックリスト

## 前提条件

- [ ]  変更内容について、実現性の検証が完了していること
- [ ]  作業内容に関する Design Doc または ADR またはそれに準ずる内容の資料が作成されていること

## 実施日調整

- [ ]  変更箇所に関する関係者の確認
    - 変更によって影響を受けるメンバーを確認
- [ ]  実施日時の調整、決定
    - 作業日を仮決めし、変更箇所に関する関係者と実施日時の調整を行う

## 実施前日までに

- [ ]  作業手順書の作成
- [ ]  作業手順書のレビュー
    - 必ずチーム内の誰かの OK をもらう
    - (レビュー OK がもらえたことがわかるスクショやリンクを貼る)
- [ ]  ステージング検証
- [ ]  本番実施時の同席者アサイン 
- [ ]  全体のリリースログに記載

## 実施当日

- [ ]  作業開始連絡
- 作業が問題なく完了した場合
    - [ ]  変更に関する動作確認
- 作業時や完了後の確認にて問題があった場合
    - [ ]  切り戻し判断ポイントに従って切り戻しを実施
    - ユーザー影響があった場合、ポストモーテムを作成(これは後日対応)
- [ ]  作業完了連絡


これらをやるとどんなことが嬉しい?

運用していての感想ですが、以下の効果が出ていると思います。

  • 作業品質が自然と上がる
    • ドキュメントを作成することで、自分でおかしな点や足りない点に気づく。
    • ドキュメントをレビューしてもらうことで、自身では気づかなかった不足などを指摘してもらえる。
  • 作業状況が見える
    • ドキュメントの作成内容から、何をやっていて・何に困りそうかが見えやすい。
    • ドキュメントから各メンバの認識している状態が把握できる(認識内容の見える化)。
      • ドキュメント内容から、認識ズレが見えやすい。
        • Slackなどの非同期コミュニケーションだと、相手が把握している内容が見えづらいのでコミュニケーションの補完になる。
  • 作業の記録がされる(後から見返せる)
    • 問題が発生した時に遡り、原因を特定しやすい。
    • 新規メンバなど知らない人が見ても今までの内容が大枠わかる。

タスクの流れ

このドキュメント施策をやる前提でタスクを進めると、こんな流れになります。
ドキュメントを作る→レビューする をタスクの中で自然に組み込む。
チェックポイントのようにドキュメントを作るのが大事だと思っています!


まとめ

インフラチームの施策を紹介しました。いかがでしたでしょうか。

ドキュメントって作るの面倒になりがちですが、後の自分や他の人を助けてくれます。
タスクの流れにドキュメント作成を組み込むことで、無理なくドキュメントが出来上がり、チーム内で円滑に作業が進められます。
チームで進める上で仕組みって大事だなと改めて感じました。

今回の施策は、インフラチームに限らずバックエンドやモバイルのような他の役割でも同じような感じで使えるかなと思います。
例えば、チェックリストはソースコードのプルリクエストでのチェックに変えるなど。気になったという方は活用してみて頂けると。

このような施策を活用しながら、ますますaskenの成長のために活動できればと思います!