技術ブログで公開する記事の品質を安定させ、効率的に執筆できるよう、 CI の導入に着手しました。
技術ブログを継続的に運営する中で、多くのメンバーが執筆に参加しています。 多様な視点の記事を公開できる一方で、技術ブログ全体として一定の品質を担保する必要があります。 人の目でレビューすることはもちろん必要ですが、中でも自動化可能な部分は機械に任せられるように環境整備を進めています。
この記事では、CIの環境や検証内容についてお伝えします。
CIの環境
記事の執筆にあたっては、過去の記事にもある通り一部Google Docsで執筆されている記事を除きGithubのリポジトリでバージョンを管理しています。
Github を利用しているということで CI の選択肢としては Github Actions が真っ先に候補となりますが、今回は AWS CodeBuildを採用しました。
AWS CodeBuild とは
AWS CodeBuild は、AWSが提供するクラウド上で動作するマネージドなビルドサービスです。
N予備校では今回このブログの執筆環境に導入する前から採用をしており、主に継続的インテグレーション（CI）の文脈で継続的にテストを実行するために利用しています。
開発においては、ビルドごとに環境を構成できる点や自動的にスケールをすることで複数のビルドを同時に実行できる点から採用に至りました。
N予備校の開発においては、ここ1年間では1日あたりだいたい平均で200ビルドを実行しており多いときには1日で700ビルドの実行をしています。
AWS CodeBuildを導入した経緯や実際の利用例などは後日改めて記事にできればと考えています。
検証内容
textlint
textlint は、自然言語向けのLintツールです。現時点では、次のプリセットおよびルールを有効にしています。
- textlint-rule-preset-preset-japanese
- 日本語向けのtextlintルールプリセットです。
- textlint-rule-preset-ja-technical-writing
- 日本語の技術文書向けのtextlintルールプリセットです。
- textlint-rule-preset-ja-spacing
- 日本語を前提にスペースの有無を決めるtextlintルールプリセットです。
- textlint-rule-prh
- 校正支援ライブラリ prh のラッパールールです。
- ほか、 Collection of textlint rule から嬉しそうなものを見繕っています。
技術文書向けプリセットは、とくに設定の適度な緩和が必要だとREADMEにも記載があります。prhのルールも辞書を育てることが重要です。ブログの記事はガチガチの技術文書と比較するといくらかの緩さを備えていてよい、記事を書いてくれる個々人の文体・作風も多少は感じられたほうがよい、という観点からさまざまに緩和の設定をしてみています。
ルール設定のレビュー過程では利用されている辞書の作りなども考慮して、開発者ブログに適していそうか、誤って検知しやすい作りになっていないかといった観点が確認されました。
記事を書いてくださる方々の筆の妨げにはならぬよう、しかし記事としての見栄えに影響することや、突っ込まれて恥ずかしい誤りを生じさせないような良き相方となるように、を目指しています。
markdown-link-check
markdown-link-check は、マークダウンテキスト中のリンク文字列を抽出し、それらのリンクが利用可能であることを確かめるツールです。
社内の資料にうっかりリンクをしてしまうとか、誤ってURLを不完全な状態で貼ってしまうようなことを防ぎます。手動チェックだと、自分もVPN内にいたので社内のリンクに気づかなかった、なんてことがよくあります。
textlint-rule-no-dead-link でも同等のことができますが、社内のネットワークからしかアクセスできないリソースにリンクしている場合に指摘したかったので、コントロールがしやすいものを選んでいます。
周辺の道具
Danger
定常的な確認事項や変更全体に対する自動検証は、Danger JS を使っています。
markdown-link-checkの結果はDanger JSを使って通知しています。
reviewdog
textlintの指摘内容は、指摘の生じている行に対するレビューコメントとしてPR上で確認できるようになっています。これには reviewdog を利用しています。
textlintの出力はreviewdogのドキュメントからリンクがある実装例1のとおりにcheckstyle形式を介しても処理できます。私たちの手元では、さらに指摘コメントから指摘されたルールのドキュメントに飛べるように、eslint-formatter-rdjson を使ってrdjsonを経由してカスタムしています。textlintの出力する結果はESLintと互換性がある2ので、間に挟むだけでもざっくり動きます。
reviewdogを使ってPRの上で指摘内容が確認できるので、lintが落ちている理由を確かめるためにCIのログを見にいかなくてもよくなりました。
将来やりたいこと
まず始められるところから CI の導入を始めた形ですが、今後より内容を拡充していきたいと考えています。 以下は拡充していきたい内容の一例です。
- Google Docs の検証
- 非エンジニアメンバーは GitHub の PR ではなく Google Docs を利用して記事を執筆することがあります。利用ツールに関わらず記事の品質を担保できるようにしたいです
- デリバリーの自動化（CD）
- GitHub や Google Docs でレビューを通過した記事をはてなブログに転記する作業は手動です。下書きの作成や本番公開も自動化したいです
より本質的な執筆作業に集中できるよう、技術ブログの執筆体制の整備を進めていきます。
We are hiring!
株式会社ドワンゴの教育事業では、一緒に未来の当たり前の教育をつくるメンバーを募集しています。 カジュアル面談も行っています。 お気軽にご連絡ください！
開発チームの取り組み、教育事業の今後については、他の記事や採用資料をご覧ください。
