｢手順書｣のススメ

こんにちは, id:papix です. この記事は, ｢はてなエンジニア Advent Calendar 2018｣の9日目の記事です.

qiita.com

昨日は id:wtatsuru さんによる, ｢基盤開発観点からみたはてなのAWS活用のこれまでとこれから｣でした.

wtatsuru.hatenadiary.com

｢手順書｣のススメ

さて, 早速本題に入っていきましょう. 皆さんは｢手順書｣を書いていますか? 自分はと言うと, 最近そこそこの規模のオペレーションが必要なタスクを担当する機会が多く, その度に手順書を書いて, レビューしてもらってからオペレーションをするようにしています. 例えば, 今年実施した｢はてなが提供するドメインを利用したブログのHTTPS化対応｣のリリースの時は, このような手順書を書いていました:

この時は, GitHubのIssueに手順書を用意していました. GitHubの場合, IssueやPull Requestに,

- [ ] ほげほげ...

といったフォーマットで手順書を書いておくと, [ ]の部分が自動的にチェックボックスになるので, 非常に便利です. ちなみにチェックを入れると[ ]が[x]に変わります.

｢手順書｣の利点

手順書を用意する際の問題点は, やはり｢用意に時間がかかる｣という点でしょう. オペレーションを実施するにあたって, 役立つ手順書を作り込むには, レビューの時間を含めてそこそこに時間がかかります. とはいえ, 手順書を用意すると, そのコストを上回る利点があると思っています. 具体的には...

• オペレーションの際, 考えることが減る
  • 予め, 必要な作業やそれを実現するためのコマンドを網羅しておくことで, オペレーション中に｢どうすればいいんだっけ?｣と悩む機会が減ります
    • オペレーション中に悩み始めると, 特に時間がかかればかかるほど, 焦りに繋がります. 焦りはオペレーションミスの原因になりがちなので, それを防ぐのは非常に重要です
  • また, オペレーションの中止基準についても事前に手順書で定めておくと, 実際にトラブルが起きた時悩まずに判断出来ます
    • 例えば, ｢○○の作業後, エラーレートがXX%を越えたらオペレーションを中止して切り戻す｣とか...
    • これもまた, 事前に手順書で定めておかないと都度考慮する必要があり, 焦りに繋がります
• 事前にオペレーションの内容を共有できる/レビュー出来る
  • 個人的には, これが一番大きなメリットだと思います
  • 実施する作業を一度手順書という形で文章に落とし込むことで, チームメイトからレビューしてもらうことができます
    • レビューすることで, より良い作業手順を練り上げることができます
  • 知識の共有という点でも有用です
    • 新しく入ったメンバーは, 手順書を読むことで, ｢○○を実施するためには, ✕✕をすればよい｣といった勘所を掴むことができます
    • また, レビューの中で, ｢実はこのオペレーションは不要｣だとか, ｢こうやった方が楽｣といった知見の共有も出来ます
• 時と場合によっては再利用が出来る
  • 例えばミドルウェアのバージョンアップの手順書を一度用意しておけば, 将来更に次のバージョンへアップグレードをする際, 概ね再利用できるはずです

自分自身, 最近ちょっとしたバージョンアップを実施するための手順書を書く機会があったのですが, その中でこれまでうろ覚えだったインフラ周りのオペレーション方法について整理することが出来て, 非常に有用でした. チーム異動や転職などで新しい環境に至った時, ｢手順書を書いてみる｣というのは, そのチームに慣れる良い方法の1つかも...? と思います(すでにチームで手順書が用意されているなら, 少し冗長に(丁寧に)したものを作ってみる, というのも有用でしょう).

｢手順書｣を書く時に気をつけていること

• 必要な連絡/周知なども網羅する
  • ｢手順書｣と言うと, 実際にコマンドを入力したりして作業する部分に注目しがちですが, 実際に業務の中でオペレーションをする際は, それ以外の手順も必要になりがちです
  • 例えば, リリース前に然るべきメンバーに周知したり, 関係部署に共有したりするのも, 立派な手順の1つです
    • そういった作業を忘れないように, 手順書に織り込んでおきましょう
• 実際に入力するコマンドまで丁寧に書く
  • ｢○○する｣だけでなく, ｢○○するために, サーバ上でxxxxxxというコマンドを入力する｣まで書いておく... というイメージです
  • 特に, コマンドのオプションが多い/長い時は, 予め手順書にコマンドとオプションを書いておいて, 実行するときはそれをコピペする... くらいにしておいた方がミスを防げます
    • 実際に作業を始めた時, コマンドやオプションを間違えて覚えてしまっていると非常に焦ります... なので, 手順書に書いておいて, 事前にレビューしてもらうのが大事です
• 中止基準や切り戻し方法も定めておく
  • 中止基準を定めておくと, 問題が発生した時に, 進むか中止するかの判断を悩まずに済む... というのは, 利点でも述べました
  • そういった事態はなるべく防ぎたいですが, とはいえそうなってしまった時のために, 作業を中止し, 作業開始前の状態に戻す方法についても, 手順書に書いておくのが大事です
    • 特に複雑なオペレーションをする場合, 作業を中止する, と決めたはいいものの, そこから原状復帰する方法がまとまっていないと, 非常に焦ります
      • 得てしてこういう時にミスが起きて, 二次災害が起きたりします...
    • そうならないように, 原状復帰の方法についても手順書に盛り込み, またレビューしてもらいましょう

実際に手順書を書いている中で自分自身で気づいたり, 或いはレビューの中で指摘してもらったりして, 上記のようなポイントを意識しながら手順書を書くようにしています. これらを意識しながら手順書を用意すると, そこそこ時間はかかる(オペレーションの規模にもよりますが, それなりの規模の作業をするのであれば, 準備とレビューで3日くらいは普通に準備期間として必要になると思って良いと思います)とは思いますが, 先に述べたようにそれを上回るメリットがあると思っています.

...まあ, ここまで書いておいて, ｢割とエンジニアって日常的に手順書を書くのでは...?｣と思ったりしたのですが, もし, ｢手順書, 書いたことないな...｣とか, ｢既に用意してある/用意してもらった手順書を, 作業するだけだったな...｣という方が, もしもいらっしゃったら, 自分自身の手で手順書を書いてみると, いろいろ気づきや学びがあると思うので, 是非やってみて頂きたいと思います.

明日は...

明日の｢はてなエンジニア Advent Calendar 2018｣は, id:masawada さんが担当です. 果たしてどのような後頭部が見れるのか, 楽しみですね.

YAPC::Tokyo 2019に, ｢チームが前に進み続けるために僕たちが考えたこと｣というトークでproposalを出しました

というわけで, タイトルの通り, YAPC::Tokyo 2019にproposalを出しました. ｢proposal出した, というエントリ書いていいですか?｣と中の人に聞いたところ｢いいですよ!｣と言われたので, YAPC::Tokyo 2019の宣伝も兼ねてエントリを書くことにしました.

yapcjapan.org

proposal: ｢チームが前に進み続けるために僕たちが考えたこと｣

"モノをつくる"という過程において, 常に順風満帆であり続けることはないでしょう. 何か調子が良くない, 何故かうまくいかない. チームとして前に進めていない... そう感じる時があるかもしれません.

まさに自分が, 所属しているチームでそういった雰囲気を感じ始めた時, チャレンジしたのが｢スクラム｣でした. エンジニアとスクラムマスターを兼業し, スクラムの導入によって, チームが前に進み続けられるよう, 試行錯誤を始めました.

このトークでは, 業務の中で直面した課題や壁に対して, スクラムを導入してどのように立ち向かっていったのか, そしてそれによって, チームがどう変わって, それに伴ってスクラムの様子がどう変わっていったのかを軸に, 今所属しているチームにおけるスクラムの様子を, ありのままにお伝えします.

具体的には, 以下のような話題が含まれる予定です:

- 感じていた停滞感 - スクラムを導入するまでのアクション - スクラムイベントのご紹介 〜はてなブログMediaチームの場合〜 - スクラム導入の成果 - スクラムでチームが変わって, チームがスクラムを変えていく - ｢ゴールを目指す｣スクラムと｢前に進み続ける｣スクラム - 自分たちの今後の展望と課題

兼業スクラムマスターが孤軍奮闘している一事例として, お聞き頂けると幸いです.

ここ半年ちょっとくらい, エンジニア兼スクラムマスターといったポジションを担わせてもらっていて, その経緯や体験, 気づきなどを5月と11月の吉祥寺.pmで発表させてもらったのですが, ありがたいことにどちらの発表でもたくさんの反響や感想を頂けたので, その総集編といった立ち位置の発表にしたいと思っています.

...ところで, ｢YAPCなのにPerlの話題が1mmもないやん!?｣という声が聞こえてきそうですが, ｢Perlでプロダクト開発しているチームでスクラム導入した話｣なのでこれも立派にPerlの話題だと思っています!!!!!! ...ということでよろしくお願いします.

トーク応募期間、延長しました!https://t.co/uwnfzj8FHj https://t.co/uwnfzj8FHj

— yapcjapan (@yapcjapan) November 27, 2018

なんとトーク応募期間が延長されているので, Perlに関するネタがある方はもちろん, そうでない方も, サクッとproposalを提出してみてはいかがでしょうか!

｢Rejectcon 2018｣ではてなブログのHTTPS化について話しました & GeekOutにインタビューしていただきました

先月末の話ではありますが, ｢Rejectcon 2018｣に登壇する機会を頂き, はてなブログのHTTPS化について話しました:

更に, HTTPS化のあれこれについてGeekOutにインタビューしていただきました. こういった媒体でのインタビュー体験は初めてだったのですが, 話しつつ, いろいろ振り返ることができて面白い体験でした.

geek-out.jp

｢Rejectcon 2018｣の資料とGeekOutのインタビュー, そして｢builderscon tokyo 2018｣で, id:aereal さんが発表された｢ブログサービスのHTTPS化を支えたAWSで作るピタゴラスイッチ｣の資料をあわせて見れば, はてなブログHTTPS化の裏側についてはほぼ語り尽くせているのではないか... と勝手に思っています.

Let's Encryptの登場などもあって, WebサービスのHTTPS化の流れはますます進んでいます. これから登場するWebサービスは, もはや｢最初からHTTPSに対応していて当たり前｣になっていくでしょう. その過渡期で, ｢WebサービスをHTTPS化する｣というアクションに携われたことはなかなか良い体験でしたし, インタビューでも語っていますがエンジニアとして学んだこと, 得たことも多かったです. その辺り, 今後にうまく活かしていきたいですね.

｢mackerel-plugin-nature-remo｣がmkr plugin installに対応しました

Mackerel UGとIDCFクラウド UGの合同イベントで, id:Songmu さんから｢mackerel-plugin-nature-remo, 使いたいからplugin対応してよ｣的なことを言われたので, ｢やってみるか!｣ということでやってみました. 成果物はこちら:

github.com

最初は｢結構面倒そう?｣と最初は思っていたのですが, 思っていた以上に簡単でした. というのも, サンプルリポジトリを使った丁寧な解説が用意されているので, それに沿って準備していけば準備については1時間もかかりません.

mackerel.io

今回は, ドキュメントを参考にして, このようなMakefileを作りました. ここまで用意すれば, あとはgitでタグを打って, make dist & make release でリリースが完了します. 見どころとしてはlinux/mipsleのバイナリも生成しているところで, 要するにEdgeRouter X用です.

...というわけで, これでmkr plugin install papix/mackerel-plugin-nature-remo というコマンド一発で, ｢mackerel-plugin-nature-remo｣のプラグインを簡単にインストール出来るようになりました. 次はmackerelio/plugin-registryに登録するところまでやってみたいと思っています(Pull Requestを送ってマージされるかどうかはわからない...).

｢アジャイルな見積もりと計画づくり｣読んだ

アジャイルな見積りと計画づくり ~価値あるソフトウェアを育てる概念と技法~

ここ半年くらい, スクラムマスターとして｢アジャイルサムライ｣や｢カイゼンジャーニー｣なども参考にして, チームにスクラムの導入を試みています. ある程度, チームの開発がうまく進んできていると思うのですが, とはいえ"見積もり"に関する部分について, もっとうまくやっていけるのでは? という気がしていました. そのときに, 確か id:daiksy さんに紹介頂いて読み始めたのが｢アジャイルな見積もりと計画づくり｣でした.

内容としては, ｢アジャイルサムライ｣や｢カイゼンジャーニー｣でも紹介されていた"見積もり"に関する内容を, 懇切丁寧に書かれている... という感じで, 特にユーザーストーリーに関する話題は, 今チームでも試行錯誤している部分だったので非常に参考になりました.

あとは, ｢2週間 = 1スプリントを6回繰り返した後, 1週間を開発メンバーが自由なアクションをできる時間にするとバランスが良い｣, といったやり方が紹介されていて, その辺りを参考にして会社の期末に1週間程度各々がやりたい事に取り組める時間を作る提案をしたところ, うまくOKが出て, コードの整備や実験的な機能の追加などに取り組めたので良かったです.

チームで開発していくにあたって, ｢見積もりをして, 計画を作る｣という所は結構根幹を担っていると思っていて, そういう意味ではチームが動き出す段階でしっかりした仕組み(フロー)ができていた方が良いし, それが定着してきた段階でガラッと変えるのは難しい(再び定着するまで時間がかかってしまう)ので, もしまた1からスクラムの仕組みを整える機会があったら, その時はこの本に目を通してからやり方を組み立てたいですね. そう考えた時に今のチームを見ると, 最初に組み立てたやり方が定着してきている状態なので, この本で得た知見を反映させるためにも, チームの変化(人事異動等)のタイミングなどを見計らいつつ, ちょっとずつ改良していくと良いのかなーと思ったりしています.