会社ブログの記事を"ペアブロギング"してみた

エンジニア テックブログ

こんにちは。

メディアサービス開発部、Webアプリケーション開発課のフサギコ(髙﨑)です。

Ruby on Railsによるバックエンドの実装運用と、AWSによるサービスインフラの設計構築を中心とした、いわゆるテックリードのような立ち位置で働いています。

本記事では、本ブログへ公開する記事を執筆するにあたって、二人で共同執筆してみたことについてお話します。

会社ブログって書くの難しくない？

会社ブログに記事を書くのは難しい、億劫である、と感じる人も多いのではないかと思います。

では、そう感じるのはなぜでしょうか。

  • 普段やっていることが記事を書くに値すると思えない
  • 書く意義が感じられない
  • 記事本文の流れを整理するのが難しい
  • 書いているうちに規模が大きくなり、修正方針が二転三転してしまって終わらなくなる
  • せっかく書いたのにレビューでコメントが多すぎてやる気が削がれてしまう

などが挙げられるんじゃないかと思います。

これらのうち普段やっていることが記事を書くに値すると思えない、書く意義が感じられないについては僕個人は比較的割り切っていて、

  • 会社ブログだからといって新規性がある、巷から見てカッコよさそうに見えることしか書いていけないわけではない
  • 仕事でやったこと、頑張ったことを大々的に書けるのは会社ブログだけ
    • 個人の技術ブログで書こうとするとどうしても仕事に支障がないように抽象化、一般化しないといけない
    • その点会社ブログでならある程度赤裸々に書けるし、むしろそう書いたほうがいい
    • 個人ブログには「会社ブログを書いた」という記事を書けばいい、万が一転職活動をすることになってもそれを見せればいい
  • 会社ブログを読んで興味をもってくれた人が入社して手伝ってくれたら楽になるなぁ

などと思いながら書いています。

一方、三つ目以降の記事本文の流れを整理するのが難しい、書いているうちに規模が大きくなり、修正方針が二転三転してしまって終わらなくなる、せっかく書いたのにレビューでコメントが多すぎてやる気が削がれてしまうについては、コードでなく文章を書くという違いからなかなか動き出せなかったり、肩肘が張ってしまっているのではないかと思います。

もしコードを書いているときにそのような迷いに直面したとすると、我々はどうしているでしょうか。そう、ペアプログラミングです。 ならば、ここは試しに、ペアプロ…ならぬペアブロギング、ペアブロをしてみましょう。

ペアブロギングのやりかた

ペアブロギングには皆さんお馴染みのGoogle Documentを使いました。

次の画像が、先日公開したNext.jsのコンテナからVercelへの移行とISRを有効化する際のハマりどころという記事を同僚のnerikeshiと一緒にペアブロギングをしたGoogle Documentの実際のスクリーンショットです。

ほかにコンフルエンス、VSCodeのLiveShareも試したのですが、

  • コンフルエンスはMarkdownを自動変換してしまい、その切り方も見つけられなかった
  • VSCodeのLiveShareはテキストエディタなので当然自動変換はされないが、画像を貼れないので画像が含まれる記事では完成状態の想像が難しかった

その点Google Documentでは、

  • ファイルメニュー→ページ設定→ページ分けなし
  • ツールメニュー→設定
    • 自動的にリストを検出をOFF
    • Markdownを自動検出するをOFF

という設定で使えばこのように、記事中で使う画像も直接貼りつつ文章の共同編集も快適に行えました。
ただし、Google Document上に貼った画像をGoogle Document上でコピーしてもWindowsのクリップボードでは画像として扱われなかったため、記事に貼る画像は別途ファイルとして保存しておかなければなりませんでした。

Markdownやリストの自動検出をOFFにするのは、書きあがった文章をMarkdownモードのはてなブログに直接コピー&ペーストするため、勝手に変換されると困るからです。

ここからは、先にも挙げたVercel移行についての記事を例として、ペアブロギングの手順について簡単に触れたいと思います。

記事の全体の流れを決める

文章となると頭からだらだら書いてしまいがちですがぐっとこらえて、まずは箇条書きで全体の流れを決めました。

といってもこの時点では記事固有の内容は一切ありません。担当しているプロダクトで課題があって、対処した、といういわゆる事例系の記事なので、ほとんど定型的な流れです。

- 挨拶、自己紹介、何についての記事かの宣言
- 紹介する対象の概要
- 何が課題だったか
- その課題に対してどのように対処したか
- その過程で何に迷ったか、何が難しかったか
- 対処した結果何が嬉しくなったか
- まだ残っている課題はあるか、今後の展望
- まとめ、採用情報ページへのリンク

箇条書きのまま、記事固有の情報を加えていく

先の箇条書きに対して、記事固有の内容を書き加えていきます。 この時点ではまだ箇条書きです。

- 挨拶、自己紹介、何についての記事かの宣言
  - 本記事では、コンテナで稼働させていたNext.jsアプリケーションのVercelへの移行と、それに付随して行ったISR導入時に起きたハマりどころについてお話しします。

## 一迅プラスとは
- インフラ構成についての記事から持ってくる

## 何が課題だったか
- 突発負荷の話
  - googlebotなどのクローラのためにほとんどのページをSSRで構築している
  - 一部人気作品ではSNSでのバズなどで予測できないタイミングで多大な突発負荷がかかる
  - オートスケールは設定していたが、負荷が突発的すぎて対応できない
  - そもそもその前段のロードバランサーのレベルでエラーが起こってしまった
    - ウォームアップしておけばよかったがそこまで予測できなかった
    - 今後も今回のようなことが起こることを見越すと構成を根本的に見直したほうがよいという結論に至った

## その課題に対してどのように対処したか
- Next.jsのSSR、ISRについて（かんたんに）
- 負荷が大きいページを中心にISR化すればページの構成要素をほとんど静的ファイルにできる⇨CDNで捌けるはず
- コンテナベースで動かし続ける場合はキャッシュ不整合の問題があるためISR化できない
  - 厳密にはできなくもないが並列化できないので厳しい
- Vercelへ移行し、その後ISRを導入する方向で進めた


## その過程で何に迷ったか、何が難しかったか
- DNSの話
  - CNAMEと書いてあったがAでもよいという返答が来た（この時点では）
- SSL証明書の話
  - 既にサービス中のWebサービスを移行するにあたって、事前にSSL証明書を発行しておくことはできない
  - 厳密にはサービス断になるのでメンテのお知らせとかがいるかも
  - 実際には1分前後で発行された
- ISR化したページが404になったときのrevalidateの挙動について
  - getStaticPropsがnotFound: trueを返すとき、revalidateの記述を忘れていた
  - revalidateが省略されたときは永続的にそのキャッシュが使われる（404が出るとそのページはキャッシュが消えない限りずっと404になり続ける）
  - 応急処置としてVercel上で再deployをかけキャッシュを飛ばした
- 根本的な対応としてnotFound: true時のrevalidateを設定した


## 対処した結果何が嬉しくなったか
- Vercelに移設されて以降、突発的なアクセス急増にも心配要らなくなっている
- デプロイが速くなった
- CORSの設定を変更して、PRブランチごとにプレビューできるようになった
- ステージングがVPN不要になった


## まだ残っている課題はあるか、今後の展望
- SSRのページが複数残っているためISRにしていきたい


## まとめ、採用情報ページへのリンク
- 本記事では...についてご紹介しました
- getStaticPropsの設定漏れは起こりやすく、本番で不意に発生して問題になることが多そうなので気をつけたい
- 採用情報ページへ

実際に文章を書く

前項の箇条書きの状態まで持ってこれれば、あとはもう箇条書きを通常の文章に変換するだけです。

二人いるので文章表現に迷わない部分については手分けすれば2倍の速度で進みますし、迷ったらその場で相談できます。

記事中に貼った画像についても画面共有しながらdraw.ioを使って描いたり、Slackから探してきたりしました。

その結果として出来上がった記事が、既に挙げていますが下記の記事です。

developers.bookwalker.jp

実作業時間は、nerikeshiがある程度先に書いていた分もありますが、2時間半ほどでした。

共同執筆者の感想

こんにちは、共同執筆者のnerikeshiです。 今回、フサギコに協力してもらえたことで、長く編集中のまま眠っていたブログ記事を完成させることができました。

ブログ記事を書くことに慣れていない自分のような方がまず悩むのが書き始めだと思うのですが、そこをサポートしてくれるメンバーがいたことで、 だんだん筆がのってゆき、いつしかほぼ一人で書き進められるようになりました。

ペアブロギングはトレーニングの面でも、知見の保持者が執筆に慣れていないばかりに眠ってしまっている知見のアウトプットを推進できるという面でも有用な手法だと感じています。 ぜひ試してみてください。

まとめ

本記事では、本ブログへ公開する記事を執筆するにあたって、二人で共同執筆してみたことについてお話しました。

シンプルな文書の共同編集においてはやはり、Google Documentに勝るものはないと思いました。 僕個人としては結構楽しかったので、機会があれば他の同僚ともやってみたいと思っています。

ブックウォーカーでは物理・電子・Web連載問わず漫画や本が好き、あるいは本ブログのような情報発信にも興味があるWebアプリケーションエンジニアを募集しています。

もし興味がありましたら、まずはカジュアル面談からでも、ぜひブックウォーカーの採用情報ページよりご連絡ください。