作業マニュアルをGithubで管理＆CLIで記載を徹底しました。

データエンジニアをしています。
現在チームとして、データ連携業務をオペレーション化し、作業の簡略化＆標準化を目指しています。
その一環で、データ連携業務の作業マニュアルをGithubで管理＆CLIベースでの手順記載にリプレイスする活動をしたので、それについて共有します。

以前のマニュアル管理の課題

• Google Slideで管理していたので...
  • 更新履歴が追いづらい
  • 誰がいつ何を変更したのかわかりづらい
  • マニュアル全体の内容の概観がわかりづらい
  • スライド1ページに記載できる情報量が少なく、作業マニュアルの全体の分量が膨大になってしまう
• GUIベースで手順を記載していたので...
  • クラウドサービスの頻繁なUI変更に弱い
    • 内容が陳腐化しやすい
    • 再現性が低くなる

Github管理にしたことによる改善事項

• 更新履歴を管理できるようになった
• 誰がいつ何を変更したのかわかるようになった
• マニュアル全体の内容の概観がわかりやすくなった
  • いま全体のどのあたりの作業をしているのかわかりやすくなった
• markdown記法が使用できるので、1から作成するときの作りやすさが向上した
• レビューに強制力をもたせることも可能になった
• マニュアルのメンテナンスに対するメンタル面での障壁が取り除かれた

後半3点について、詳細を記載していきたいと思います。

markdown記法による作りやすさの向上

.md形式のファイルにマニュアルを作成することにより、markdown記法を使用できるようになりました。
これにより、マニュアルのアウトラインの作成から完成を目指して肉付けしていくように、構造的に文章を記載することができるようになりました。

文章の思案から詳述までを一貫して実施できることは、多くの人に読みやすいと思っていただけるようなマニュアルにするための、一助になると思いました。

レビューに強制力をもたせる

Google Slideで運用していたときには、変更内容に対して第三者がレビューをしなくても変更が反映できてしまう体制でした。
今回は主にチーム用の作業マニュアルに焦点を当てていましたので、「よりよいマニュアルをチームとして作り上げる」ことができればなと思っていました。

Githubではブランチ保護ルールを設定することができます。
今回は「mainブランチにmergeする際には、少なくとも1人のレビュワーのApproveが必要」というルールを設けました。

Githubのブランチ保護の機能を活用することで、マニュアルの変更内容に対するレビューの体制も仕組みとして構築することが可能となりました。

参考：ブランチ保護ルールを管理する

マニュアルのメンテナンスに対する気持ちの変化

以上もろもろの改善による効果だとは思いますが、マニュアルの変更に対する気持ちの変化も生まれました。

Google Slideでマニュアルを運用していたときは、下記のような場面がたくさんありました。

• 「スライド1ページごとにURLが振られているので、スライドの順番を崩すと厄介だな...」
• 「ここの手順変わったから新しいスライドにしようと思うけど、前の手順が記載されたスライド消したら切り戻しめちゃくちゃめんどいよな...」
• 「このページとこのページのフォントあってないな...変更めんどいから気づかなかったことにしよう...」
• 「スライドのこの部分変更したんだけど、変更前の様子がわからないから、レビューしてもらうの大変だな...仕方ないから前のバージョンも複製して残しておくか...」

もちろんGoogle Slideが悪いとは思いません。
これらはツールの強み・弱みの弱みの部分を、悲しくも多大に引き受けてしまった結果だと思います。

また、これらの心理的なハードルは、身近なトイルを増加させてしまうことを助長していたとも思います。

一方、Githubでのマニュアル運用に変えた結果、
マニュアルのこの部分ちょっと正確じゃないから、空いた時間に軽く直してPull Requestあげとくかー
くらいのノリで、気軽にマニュアル変更をリクエストできるようになりました。
マニュアルの運用に対するハードはだいぶ下がったのかなと感じます。

CLIベースの記載にしたことによる改善事項

• クラウドサービスの頻繁なUI変更に影響されないようになった
  • マニュアルメンテナンスコストの軽減
  • 新規参入者への作業依頼がしやすくなった

後半2点について、詳細を記載していきたいと思います。

マニュアルメンテナンスコストの軽減

クラウドサービスのUIって頻繁に変更されますよね。
より便利に見やすく使いやすくなるのはとてもありがたいのですが、マニュアルをGUIのベースで運用していくことには限界がありました。

また、UIの変更にマニュアルが追いつかず、

• 「マニュアルにあるこのボタン、見当たらないんですけど...」
• 「UI変更はあったけどよしなに解釈して手順通りにやったと思い込んでいたら、実はある設定項目を見落としていた」

などが発生し、事故のもとになってしまうことが危惧されました。

一方、CLIベースの手順記載を徹底したことで、頻繁に起こるUIの変更に強いマニュアルとすることができました。
それによって、マニュアルのメンテナンスの負担も軽減されることとなりました。

新規参入者への作業依頼がしやすくなった

（前述の問題が起こりうる可能性はあれど）ある程度慣れた作業者にとっては、習熟度によってUIの変更をうまく吸収して、作業はなんとかできるといった場合がありますが、新規参入者への作業依頼はしづらく感じていました。
特に再現性の点で不安に思い、しばらくの間は習熟度の高いメンバーが並走してあげるみたいなこともしばしばありました。

一方、CLIベースの手順記載とすることで、再現性の高い作業マニュアルとなり、いつだれが実行しても期待する結果になることがある程度担保されるようになりました。
これにより、任せる方の不安も取り除かれましたし、任される方も安心して作業に取り組むことができるようになったのかなと思います。

今後の展望

• 他の作業マニュアルもGithubのリポジトリで管理したい
• 他の定形作業や身近なトイルもCLI化で簡略化＆標準化したい
• CLI化の発展として、一連の作業のひとまとまりについては、シェルスクリプト化などによりもっとラクにできそう