Mobile Factory Tech Blog

技術好きな方へ!モバイルファクトリーのエンジニアたちが楽しい技術話をお届けします!

モバファクテックブログの記事管理を GitHub リポジトリに乗せてアドベントカレンダーを運用してみた

メリークリスマス 🎉

BC チームの id:d-kimuson です。アドベントカレンダーもとうとう最終日となりました!

今年のアドベントカレンダーでは、初日の記事は僕が執筆をしました

この記事を書いていて、レビューをお願いしていたら以下のような投稿をもらいました

社内ではドキュメントサービスとして DocBase を使っているので、技術ブログの下書きを DocBase に書いていたのですが、Pull Request で行うレビューに比べてレビューがしづらいよね、というものです

課題があれば解決するのがエンジニアです

かねてからローカルで書けたほうが執筆体験良いのに... と思っていたこともあり

  • ローカルで記事を執筆できる
  • GitHub 上でレビューができる

ような仕組みを整えて、今年のアドベントカレンダーのお試し運用をしてみたので紹介します

ローカルで執筆できる環境の整備

エンジニアに限れば使い慣れたローカルの環境のほうが記事を書きやすいという人の方が多いでしょう

また、モバイルファクトリーのテックブログは、はてなブログで運用していて元々 Markdown を使えることから、下書きはローカルで書くという選択肢も取ることができました

各々のエディタのプレビュー拡張機能等で確認してもらっても良かったのですが、プレビューのスタイルもテックブログに近いほうが嬉しいよね、ということで、ローカルで動作するプレビュー用の開発サーバーも用意しました

ブログで実際に利用しているカスタム CSS をあてることで、DocBase を使うよりも本番に近いプレビューをしながら記事を書くことができるようになりました 🎉

技術的には JAMStack 系の各種フレームワーク等の中でも、特にローカルでの執筆体験の良い VitePress を利用してローカルで使うプレビューサーバーを準備しました

執筆補助ツールを利用する

また、ローカル環境では

等の優れたツールを執筆の補助として利用できるという利点があるので、これらを活かせるような仕組みを作りました

社内で利用者の多い VSCode の設定をリポジトリからまとめて配布することで

  • onSave 時に textlint, prettier で自動修正可能な問題が修正される
  • onType でスペルミスや日本語の問題点をそれぞれ cspell, textlint の拡張機能が教えてくれる

ような執筆体験で記事をかけるようになりました

また、今回は CI を整備する手間まで取れなかったので

を使うことで、コミット時に prettier, textlint, cspell の制約を課す仕組みを追加しています

これによって、VSCode を利用していない社員も、コミット時に校正ツール等の恩恵を受けることができるようになります

GitHub 上でレビューができる

構築した環境のソースコード・記事ファイルは GitHub で管理されていて、Pull Request を作ることで記事のレビューを依頼できます

コメントをいれる場所が明確ですし、ちょっとした内容であれば Suggested Change を使って提案できるのでレビューもしやすくなりました

自動デプロイはしない

GitHub で記事を管理する話になれば、必然的にマージのタイミングで CI/CD を使って記事を自動投稿したいという話にもなってきます

セルフホストしている SSG ベースのブログとかでしたらこの辺りはやりやすいんですが、モバイルファクトリーのテックブログははてなブログで運用をしているためこの辺りの仕組みを作るのは結構大変になってしまいます

今回はお試し運用であることと、仕組みを作ることが大変であることから「執筆・レビューのフローまで整備するが、実際に投稿(デプロイ)する作業は手作業で行う」という形での運用としています

使ってみた感想を聞いてみる

元々お試しでやってみようという温度感だったので、実際に記事を書いてくれた人に感想を聞いてみました!

ローカル執筆とリポジトリでのレビューのフローを今後も利用したいですか?

約 9 割が今後も利用したいという回答でした

校正ツールである textlint や cspell 等を導入していましたが、執筆の補助として役に立ちましたか?

校正ツールについても 7 割弱は好意的でした

その他感想としては

GitHub 上のリポジトリという形で記事が管理されることによって、各々が好きなエディターを使うことが出来るようになり、記事を書くのが快適になりました。

初の技術ブログ執筆でしたが、使い慣れた GitHub 上レビューフローでとてもやりやすかったです。 基本的な日本語の誤りも自動で指摘してもらえて助かりました。

のようなポジティブな感想が多かったです

レビュワー視点でも

下書き画面や DocBase だとコメント箇所の伝え方が難しいですが、GitHub を使うと行に対してコメントできるのがよかったです

コードレビューと同じ要領で記事のレビューができるので、使い勝手も分かっていてよかったです

のようなポジティブな感想をいただきました

また、個人的には、今回のリポジトリに対して機能追加やバグ修正の PR を送ってくれる有志もいたため、普段開発業務で関わらない人のレビューをしたりすることもあったのが新鮮で良かったです

一方、textlint に関しては設定しているルールが合わないこともあり、以下のような感想もありました

textlint と cspell はスペルミスや構文ミスの発見などで何回か役に立ちました!しかし、自分の文章に対するこだわりと相なれない部分もあり、CI で拒絶するほどではないと思いました。以下は textlint で気になった点です。

「思います」という文章は、技術ブログの導入や最後の感想の部分で登場することは自然です。「本格的に、厳格に、丁寧に、文章を書く必要があります」のようなリズミカルに「に」を重複させたいときも怒られてしまいます。「A や B、C、D などのように、〜〜」これも「、」を 4 回打つため怒られます。

この辺りは、人や記事によって語調も変わるので、場合によっては煩わしくなってしまうこともあり、ルール設定が難しいなと感じました

textlint では部分的に textlint を無効にする <!-- textlint-disable --> コメントが用意されているので、ルールの整備は進めつつも、一旦はコメントを使ってもらう形で案内するしかないかなと思っています

また、画像の追加についてもローカル環境だと手間になってしまうという声や、部署によってはローカルマシンで開発をしないため環境構築が手間だったという声もありました

この辺りは今後の課題として解決していきたいですね

まとめ

この記事では、はてなブログで運用しているモバファクテックブログの記事の管理を GitHub に載せて、ローカルで執筆する仕組みを作った話を紹介しました!

たかが執筆・レビュー体験の話ではありますが、会社の名前でテックブログを書いてくれる人はとても貴重です。少しでも書きやすい環境を整備してみるのはいかがでしょうか!

NextAction としては

  • やはり執筆した記事を手動で転記するのは手間なので自動でデプロイするような仕組みを整えること
  • 運用していてこの辺も textlint で怒ってほしいよね、この辺は怒らなくても良いよね、というものが見えてきたのでルールを最適化していくこと
  • 執筆体験が良くなっただけでは意味が薄いので発信自体も増やしていきたい

辺りをやっていきたいなと思っています

以上となります! それでは良いお年を!