オンラインドキュメントへCI/CDを適用している話というタイトルで発表してきた

こんにちは、普段はSkyWayの開発・運用をしている岩瀬(@iwashi86 (link is external))です。

先日、クラウドアカデミー¹という社内勉強会で、SkyWayのドキュメントに適用している継続的インテグレーション(CI)および継続的デプロイ(CD)について講演してきました。発表資料は以下になります。

内容の要約

内容を3行でまとめるとこんな感じです：

• MkDocsを使って静的WebサイトをMarkdownで書いて生成
• textlintで文章をテスト
• CircleCIを使って、ドキュメントを継続的テスト＆デプロイ

実際の講演では、前半でそれぞれの項目について詳細化して説明し、後半でライブコーディング形式で実演しました。

発表後の質疑や感想など

発表後の質疑応答コーナーで、いくつかの質問をいただきました。そこで上がった質問の1つとして、「本フローが適用できない文書はあるか？」というものがあります。ポエムなどの詩的な文書には難しいかもしれませんが、textlintでは任意のルールを作成可能 (link is external)であるため、適用範囲は独自に拡大可能です。実際には拡大せずとも、(特に)技術系文書向けに既存のルールが多く存在するため、それらを活用するだけでも品質の底上げは十分に可能です。

より便利にルールを適用するために、ルールを複数まとめている、Presetも公開されています。たとえば、日本語の技術系文書ではこのPreset (link is external)が活用できます。

また、終了後の参加者の感想として、「実際に自分のチームでも使ってみたい」などのコメントをいただきました。本勉強会に参加するのは、エンジニアだけではないため、普段からプログラムに触れるメンバ以外にも印象的だったようです。

まとめ

• クラウドアカデミーという社内勉強会で、ドキュメントにCI/CDを適用する話を講演してきました
• CI/CDにはMkDocs/textlint/CircleCI 活用しています
• textlintは様々な文書に適用可能です

みなさまも、文書の品質改善にCI/CDのフローを適用してはいかがでしょうか。