- はじめに
- Q.手順書の作成より根本原因の解決や自動化した方がいいのでは？
- なんだかんだ言ってドキュメントがあると助かる
- 運用保守だと尚のこと助かる
- 解決方法と作成のコツ
- そしたらどうなった？
- おわりに
はじめに
こんにちは、千株式会社ものづくり部のしまゆです。
2023年3月入社なので、入社から1年9ヶ月ほど経ちました。
元々SIerで運用保守をしていた期間が長かったので今回はドキュメンテーション、主に手順書についてお話ししたいと思います。
Q.手順書の作成より根本原因の解決や自動化した方がいいのでは？
A.それはもうまったくもってほんとそう
しかしながらリソースには限りがあり、関係各所と優先順位を決めて進めていく上でどうしても後回しor運用でカバーせざるを得ないことも多々あります。
色々な課題がありますのでぜひ！我こそはという方は一緒に働きませんか？
なんだかんだ言ってドキュメントがあると助かる
コードがあれば処理そのものはまぁなんとか読み解くことはできますが、「なぜこの機能が必要になった」とか「どういうパターンを想定していたか」とか「どういう意思決定だったのか」とか「どんな事情での技術選定だったか」など、コード外の情報が後々助けになることがあります。
それを知っている人がずっといてくれればいいのかもしれませんが、時の流れで転職されていたり、本人も忘れてたりするのでドキュメントとして残っているとありがたいですね。*1
弊社でも保守対応や不具合修正の際に現行機能についてのドキュメントが一部しかなく、一からコードを読み動作を検証することがありました。
現在ではものづくり部の課題として捉え、そのあたりをちゃんと残しておこうという取り組みのもと、必要に応じてADR*2やユーザー要求仕様書を作成してから開発に着手する運用になっています。*3
運用保守だと尚のこと助かる
私が所属しているチームでは運用保守が結構な割合をしめていました。
あるあるかと思いますが保守対応が忙しいと、
エラーログが通知される or 問い合わせが来る→いち早く敏感な人が反応・対応する
の流れになりがちでどんどん属人化していき、手順書を書く暇もなく次の対応や自分の開発の仕事に追われてしまう負のスパイラルになりがちです。
手順書があれば新しくチームに入った人にも先に読んでおいてもらって、いざ対応が必要になったら他の人にお任せしやすくなります。*4
また、データ更新を伴う場合のチェック表として使えたり、前回の対応を思い出せなくてSlackや課題などを検索する手間と時間を減らすことができます。
あれば助かる手順書ですが無かったり、あっても情報が古かったりすることもあります。
解決方法と作成のコツ
今までに手順書がない対応の場合は保守対応を教えてもらいながら書いたメモをもとに、とにかく作成しました。
おそらくみなさんも何かしらの情報共有ツールを利用されていると思います。「新規作成が簡単にできる」「複数人による編集がしやすい」「履歴が残るので以前の内容に戻しやすい」「差分が確認しやすい」といった便利な機能があり作成・変更のハードルが低いので都度作成するのもそれほど苦ではありませんでした。
チーム内の理解もあり案ずるより産むが易しの精神で、結局はメモを取るんならみんなが見えるところにメモを置けばいいじゃん。もうちょっと肉付けして手順書っぽく仕立てればいいじゃん。そうなったらもう手順書じゃない？ってくらいの軽い気持ちでスタートしています。
手順書を書くにあたって意識していることとしては以下のとおりです。
必要なときにパッと開ける工夫をする
情報共有ツールの問題として「たくさん記事があって埋もれる：ということがありますので、あとから検索しやすくするための工夫が必要です。
その一つとしてタイトルにエラーの文言を入れておくとか、どういう時の対応かを端的に書いたりしています。
タグがつけられるのであればタグをつけておいたり、階層で分けられるなら辿りやすいところにまとめておくと共有するときも楽です。
必要な情報を全部書く
これまでの経験から暗黙の了解について書かれてなくて苦労したことがあったため、とにかく書いておくことを意識しています。
- 「こういう権限が必要だからまず申請しておいてね」
- 「この更新をするときは○○チーム（またはユーザー）に了解を得てからやってね」
- 連絡用の定型文
- 確認用のクエリ
- 課題のクローズの仕方
など、少しおせっかいかなというレベルで書き残しています。
必要に応じてスクショや説明用の図も貼ったりしています。画面が複雑な場合だと矢印つけたり枠で囲ったりしていますが、やりすぎるとそればっかりに時間がかかってしまうのでトレードオフですね。
情報が古い手順書に追記する
自分が必要な情報だと思うことは追記します。これも暗黙の了解とか行間とか解釈の違いで判断に迷うことがあればそこを補完するようにしています。
また、変更があった箇所も適宜最新の情報に更新していくと手順書が腐りません。常に関連するリリースがあるたびに更新、だと大変なので「対応した時に変更箇所があったら」くらいの意識がちょうどいいかもしれません。
そしたらどうなった？
保守対応方法を伝授してもらうor新しい対応が出てくるたびに手順書を作成していますが、色々とメリットがありました。
属人化の解消
新しくチームに入った方に対応をお願いしやすくなりました。
もちろん最初はモブプロで対応したりしますが、手順書があることで全体の流れ、チェックするポイントが把握しやすくなり、自分が今どこの段階をやっているかがわかりやすくなります。
「手順書のおかげで対応できました」と言ってもらうこともありました。嬉しいね。
保守対応時間の短縮
前述の通り、過去対応をSlackや課題を検索・確認しなくても手順書をみれば対応できるので、余分な時間が不要になりました。
副次的なメリットとしては手順が書いてあるのでそれを見直して減らせる手順を見つけることができたり、手順書に記載した内容から根本原因が解決されることもありました。
他チームへの引き継ぎも楽々
これまでは1チームで保守を受け持っていましたが、現在のものづくり部ではドメインごとにチームが分かれどんどん開発が加速&複雑化しているのとともに、各ドメインごとにそれぞれの顧客理解が高まっている状況であることと、運用保守込みで開発のペインを解決する思考を持っていこうという方針により保守対応を各チームでそれぞれの領域を担当するようになりました。
その際に各チームにどういう対応をするかを引き継ぎしましたが、すでに手順書がありますのでこれを見てもらいながらモブプロを行うだけでスムーズに引き継ぎをすることができました。
引き継ぎ後は各チームのやりやすい手順に編集してもらうとよりよいと思います。
おわりに
アドベントカレンダーや今後のブログ更新で千株式会社では今どのような取り組みのもと課題に立ち向かっているかなど明らかになっていく予定です。
興味を持っていただいた方はこちらもどうぞ。
明日は人事部・@iwadoooo_77さんの個人制作にまつわる内容です。
