こんにちは hsbt です。先週、龍が如く外伝7をクリアして来年発売する8の体験版をプレイしたところです。8の発売日は2024年1月26日なので、そこまではゲームは一段落かなと安心していたところに、12月に発売するバルダーズ・ゲート3がとても面白いらしいという噂が出てきたので、これはプレイするしかないかなーと悩んでいるところです。1ヶ月で終えることができるボリュームなんでしょうか...。
さて、今回はANDPAD Advent Calendar 2023と 技術広報 Advent Calendar 2023の1日目として、このテックブログの執筆環境のアップデートについてご紹介します。
アンドパッドテックブログの執筆フロー
アンドパッドではテックブログの執筆は以下のようなフローで行っています。
- 執筆者がはてなブログに下書きとして投稿
- 下書きに対してチームメンバーによるレビューと反映
- 終了後にテックブログ編集部によるレビューと反映
- テックブログ編集部による最終確認後にアイキャッチ設定と予約投稿セット
テックブログに書く内容のネタだし会や緩やかな当番制度、イベント参加前後のテックブログ執筆の推奨など、1より手前に実施している施策は多数ありますが、今回は執筆から公開までのプロセスに限った内容とします。
1は、このテックブログのサービスプラットフォームであるはてなブログの編集画面から執筆を行います。アンドパッドでは Markdown 記法を用いています。ここは特筆する内容は特に有りません。
続いて 2 と 3 のレビューです。アンドパッドでは、レビューを2段階に分けています、1段階目はチームメンバー、特にチームリーダーを含めて技術的内容の正確さや表現についてのレビューを実施し、2段階目はテックブログ編集部という有志による組織上は論理的なチームで、公開する際の文章の表現や営業秘密などが含まれていないかなどの、読みやすさとコンプライアンスに即したレビューを行っています。なお私は編集部のメンバーです。
2段階のレビューの完了後に、改めて編集部で公開日と時刻を決めて、アイキャッチを設定後に予約投稿を設定します。ここは執筆者が任意に公開しても問題ありませんが、執筆者はプロダクト開発も行っているため、フローの3にある編集部によるレビューが完了したかどうかを、ハンドリングするのは負担が大きい事が多いです。そのため、アンドパッドでは2の時点で執筆者から編集部へ公開に関する ownership を移し、編集部のメンバーが外に出せるクオリティまで高めて、公開するということに責任を持っています。
テックブログのレビューの難しさ
前述したようなフローのなかで、私がアンドパッドの中で特に非効率と感じたのが、レビューのフィードバックとその反映です。はてなブログにはレビュー用の機能がないため、レビューを行う際は以下のような手順を用いていました。
- 下書きプレビューの URL を作成
- slack で下書きプレビューの URL とともにレビュー依頼
- slack のスレッドなどで指摘箇所を引用して修正案を提案したり、違和感などをフィードバック
- スレッドで個別に「〜を直しました」「〜については、〜と思ったのですがどうでしょう」というやり取りを継続
- 執筆者とレビューアーの理解の中で完了した、となったら完了
上記の手続きを段階ごとに合計2回実施していました。私が課題と感じるのは特に4と5です。slack のように上下に流れるコミュニケーションツールでは、あるコメントに対する返事はスレッド1段で行うことは容易ですが、レビューのフィードバックと、フィードバックに対するコメント、そのコメントに対するさらなるフィードバック、というようにピアレビューのようなコミュニケーションには不向きです。
また、レビューは依頼する方もされる方も、時間を使って成果物を良くしたい、と考えて行動しているので、発生したコミュニケーションについては双方が全て納得の行く形で対応すべきですが、slack で五月雨のようなフィードバックが発生した場合、うっかり見落としてしまう、ということは起こり得ます。これは気をつけるという人間の問題ではなくて使っているツールの問題です。
チームによっては、slack ではなくてレビューに Google Document を利用するチームもありますが、この場合はオリジナルであるはてなブログに記載しているものを Google Document にコピーして、レビューと反映、完了したら再度貼り付け、ということを繰り返す必要があります。画像なども含めて2つのツールの中でコピーを繰り返した結果、実ははてなブログではなく、Google Document の方が新しいバージョンだった、ということも起こりうるため編集部では、何処のものが最新バージョンか、ということに常に気を使う必要がありました。
HatenaBlog Workflows の導入
そのような課題を抱える中で HatenaBlog Workflows Boilerplate が公開されました。最初に見たときに、「自分たちが欲しかったのはこれ!」ととても嬉しくなりました。というのも、前職の GMO ペパボでは GitHub Pages でテックブログを作成しており、執筆からレビュー、公開までが全てプロダクト開発と同樣に pull-request を用いたワークフローになっていたため、成果物の品質向上をやりやすいということがありました。
この HatenaBlog Workflows を導入することで、同じような環境を作れるのではないか、と思いすぐに検証を開始しました。結論から書くと、全てを理想としていた状況にはできずレビュープロセスのみを改善できたという結果です。具体的には HatenaBlog Workflows では、以下のようなワークフローが想定されています。
- はてなブログで下書きを作成
- 下書きのタイトルを指定して、GitHub のリポジトリへ pull-request として下書きを Markdown ファイルで作成
- pull-request に対して、変更を commit し、push ではてなブログの下書きに反映
- pull-request をマージすることで下書きを公開
上記のうち、1-3を採用することで、前述したレビューの煩雑さについては大幅に解消することができました。GitHub の pull-request では、typo や単純に言い換えてしまった方がよいものについては提案という形でレビューができるので、これまでは執筆者が個別に直していた些細な修正についても、数クリックで取り込むことができるようになりました。また、「この箇所はどういう意味でしょうか?」というような、レビューアーがもった素朴な疑問についてもGitHub上に記録として残すことができるようになりました。
このレビューの記録ということを個人的には非常に重要視しています。執筆結果としてのテックブログのエントリは外に対する成果物ですが、内に対してはレビューとフィードバック、フィードバックに対する対応がコメントは内部で今後の執筆に向けた成果物となるからです。
より良い執筆環境をもとめて
レビューについては大幅に改善ができましたが、アンドパッドでは公開についてはアイキャッチを設定するとともに予約投稿を使うことにしているので、マージによる公開については採用を見送りました。この辺は GitHub Actions の scheduled workflow を使うことで指定した時間に投稿することもできそうですが、フローを変えずに一旦レビューを GitHub でやる、レビューと反映の価値を高めていくということを当たり前にできるようになってから考えることにしました。大きな問題は理解できる粒度に分割して個別撃破という作戦です。
また、導入に際して、いくつか期待した通りに動かない箇所がありました。HatenaBlog Workflows Boilerplate は OSS として公開されているので、素朴に問題を報告したり pull-request を作成しました。
- 独自ドメイン利用時に workflow に設定すべきドメインが不定 · Issue #15 · hatena/Hatena-Blog-Workflows-Boilerplate
- 空白を含むタイトルであっても pull draft を実行可能とする by hsbt · Pull Request #42 · hatena/hatenablog-workflows
企業という垣根を超えて、便利なものを作る、という取り組みは大変素晴らしいと感じます。引き続き、利用しながらも気がついた箇所は報告したり、直したりしていきます。
まとめ
以上、アンドパッドのテックブログの執筆からレビュー、公開までのフローと、HatenaBlog Workflows の導入についてご紹介しました。アンドパッドではこのような「テックブログを書くという環境」についても、絶え間なく最高のパフォーマンスを出せるように模索しながら、新しい仲間を募集しています。興味を持った方は以下のリンクをご参照ください。
