本文の内容は、2022年4月7日にRadhika Puthiyetathが投稿したブログ(https://sysdig.com/blog/adopting-docs-as-code/）を元に日本語に翻訳・再構成した内容となっております。
Sysdigでは毎年ハッカソンを開催しているおかげで、最近ではdocs-as-codeの考え方を取り入れ、ドキュメント作成の民主化を進めています。ソースコードと同様に、製品ドキュメントもバージョン管理され、同じゲートキーピングシステムが適用され、同じCI/CDパイプラインを使用して自動配信されるようになりました。
Doc-as-codeワークフロー
この記事では、Sysdigのドキュメンテーションの旅についてご紹介します。また、最終的にどのようにして現在の方式にたどり着いたのか、それによって私たちがどのように効果的で生産的な仕事ができるようになり、最終的にお客様の勝利に貢献できるのかを学びます。
なぜDoc-as-Codeなのか？
私たちは、既存のオーサリングツールがコントリビューターの要求を満たすことができない一方で、ドキュメントへのコントリビュートに熱心な専門家の数が急激に増加していることを目の当たりにしました。私たちのコントリビューターは、開発者からプロダクトマネージャー、サポートチームまで多岐にわたるため、私たちのオーサリングシステムを開発者のワークフローに統合し、円滑なコラボレーションを可能にすることが有利であると考えました。旅路：非構造化から構造化、そして半構造化へ
私たちは、GitHubの方法に着手する前に、長年にわたって公開文書の処理方法をいろいろと試してきました。構造化ツールであれ非構造化ツールであれ、これまでの試行錯誤のシステムはすべて、私たちの要件に制限されるか、適合しないことが証明されました。Sysdigのドキュメントは、当初はZendeskの記事の束として始まりました。しかし、製品が進化し、コンテンツが膨大になると、コラボレーションに最適化されたコンテンツ管理システムが必要になりました。Sysdig は Confluence を社内文書に使用しているため、次の論理的なステップは Confluence に切り替えることでした。
Confluence には独自の課題がありました。私たちが使用していたバージョンでは、トピックの再利用、バージョン管理、Sysdig のブランディングに従ってページをカスタマイズする機能など、企業向けの機能のほとんどが欠落していたのです。当時は、コンテンツ開発とドキュメントツールの両方がドキュメントチームによって完全に管理されていたのです。
| Confluence の利点 | Confluence の欠点 |
|---|---|
|
|
ドキュメントサイトにSysdigのルック＆フィールを採用するために、Sysdigを捨て、専門的なサポートを受けられるエンタープライズオーサリング・コンテンツ管理システムを採用することにしました。そして、Paligoを選択しました。
Paligoは、XMLベースのオーサリング＆コンテンツ管理システムで、エンタープライズ向けの機能のほとんどを提供していました。しかし、バージョン管理機能を持つ統合ホスティングサービスがありませんでした。バージョン管理と公開のために、GitHubと静的サイトベースのワークフローを構築する必要がありましたが、これは、私たちがすでにDoc-as-Codeシステムに入っていたことを意味します。また、XMLベースの投稿者インターフェースは、ドキュメントチームの外部の投稿者にとってはハードルとなりました。また、サブジェクト・マター・エキスパートは、実験機能のコンテンツ・リポジトリをGitHubで構築するようになり、そのコンテンツをXMLベースのPaligoに取り込むのは悪夢となりました。コンテンツ作成を効率化し、より幅広いチームへの貢献を可能にするために、この切り替えは必然的なものでした。
| Paligoのメリット | Paligoのデメリット |
|---|---|
|
|
要するに、Zendeskの記事はサポート組織には適していても、完全なエンドツーエンドの製品ドキュメントには適していなかったということです。Confluenceは文書作成者にとっては非常に有効でしたが、バージョンを保持したり、Sysdigのブランディングに従ったりするには、あまりに慣習的でした。どのシステムも、私たちの要求をすべて満たしてくれるとは思えませんでした。
ハッカソン効果
ハッカソンとは、部門を超えたチームが創造的なアイデアに取り組む、時間枠のあるイベントです。Sysdigでは、毎年ハッカソンを開催し、社員が革新的なアイデアを提案し、普段はあまり一緒に仕事をすることのない同僚とコラボレーションする機会を提供しています。Sysdigのハッカソンでは、不可能を可能にします。私たちのチームは、PaligoのXMLコンテンツを、革新的な社内ツールを使ってDoc-as-Codeスキームに移植するアイデアを提案しました。
パーキンソンの法則にあるように、”仕事は完成までの時間を埋めるために拡大する “のです。ハッカソンのおかげで、コンテンツはGithubにmarkdown形式で移植され、美的なHugo-Docsyベースのウェブサイトが稼動して、この努力は終了したのです。
変換ツール
PaligoのDocBook XMLコンテンツをDoc-as-Codeに適したmarkdown形式に移植するには、ある程度の自動化が必要であり、そのために明らかに選ばれたのがpandocでした。これはDocBookとmarkdownの両方をサポートするオープンソースのユニバーサルドキュメントコンバータです。しかし、単にpandocコマンドを実行するだけでは、XMLが望ましい形式のマークダウンに変換されることを期待することはできません。すべてのDocBookタグが簡単にmarkdownに変換できるわけではありません。XMLにはあってmarkdownにはない属性がたくさんあり、その上、Paligo独自の識別子は異なる扱いが必要です。そのため、Hackathonチームの焦点は、pandocコマンドを実行する前にXMLファイルを改良し、変換後に変換されたmarkdownファイル内のタグをクリーンアップすることでした。XMLファイルの修正には、属性をpandocが識別できるものに置き換えることが含まれますが、これに限定されるものではありません。変換後の修正は、主にWebサイトでのコンテンツの表示方法を洗練させるために行われました。
その結果、この問題を解決し、変換を自動化するためのPythonスクリプトが完成しました。
CI/CDパイプライン
ドキュメントサイトの構築には、豊富な機能を持つHugo static site generator with Docsy themeを選びました。Hugoは高速で、拡張性の高い豊富な機能を備えており、サポートのための活発なコミュニティもあります。Docsyは、ダークテーマ、RSSフィードのサポート、APIのswagger統合などの機能を備えており、いずれはサイトに導入する予定です。Netlifyは起動が速く、プレビューや本番ビルドをホストするためのGithubリポジトリとの統合も簡単です。公開フローは、各Pull Requestがプレビュービルドを生成するように設計されており、レビュアーはウェブサイトに表示されるようなコンテンツを見ることができます。この仕組みにより、品質を犠牲にすることなく、ドキュメントの公開ペースを加速させることができました。
Docs-as-CodeからDocs-from-Codeへ
docs-as-code方式への移行は、文書公開の自動化を可能にしただけでなく、文書開発の自動化も可能にしました。ドキュメントのギャップは、ソースコードの修正とドキュメントの修正が同期していない場合に発生することがほとんどです。残念ながら、これは、プロジェクトサイクルの時間的制約の中で、さまざまな人がコードにコントリビュートする場合によくあることです。私たちが考案した ”doc-from-code” 方式は、このようなケースを解決しようとするものです。
私たちのドキュメントの一部は、プロジェクト内のソースコードや設定ファイルを解析することでコンテンツを生成するように自動化されています。私たちは、ソースコードを解析し、ドキュメント内のコンテンツをレンダリングするためのテンプレート群を開発しました。テンプレートは定期的に、または新しいリリースが発行されたときに実行されます。このプロセスはまた、docsの更新バージョンを生成し、docsチームによってレビューされ公開される準備が整った自動プルリクエストを作成します。これにより、我々のアプリケーションのソースコードに誰がコントリビュートしても、ドキュメントは常に更新されることが保証されます。また、コードを解析してドキュメントを生成することで、時間とリソースを節約し、コンテンツとフォーマットの一貫性を保つことができます。
最後に、最新のハッカソンプロジェクトの1つは、メトリクス辞書のツールチップとドキュメントの作成を自動化するために、このワークフローを反復しています。メトリクス辞書の作成を自動化することで、部門を超えたチームがメトリクス定義の改善に密接に協力するようになり、それによって、手動によるエラーやパスへの摩擦がなくなることが期待されます。
まとめ
新しい仕組みでは、Sysdigのドキュメントはソースコードと一緒にGitHubに保存・管理されています。SaaS製品やOSSコンポーネントを接着して構築された現在のオーサリング環境は、ドキュメントチームと開発チームが共同でメンテナンスしています。その結果、簡単にドキュメントをコントリビュートするための障壁となる、ライセンスのある構造化オーサリングツールを切り離しました。| Docs-as-Codeの利点 | Docs-as-Codeの欠点 |
|---|---|
|
私たちはまだ模索と実験を続けており、その結果をまた報告する予定です！ |
この切り替えにより、本番稼動後1ヶ月でコントリビューターの数が15倍、ドキュメントのデプロイメント時間が数秒に短縮されるなど、大きな成功を収めました。手作業のレビュープロセスを排除し、自動化されたウェブベースのステージング環境を導入することで、ドキュメントの発行が迅速化されました。Docs-as-codeは、ドキュメント開発に関連する反復的な活動を自動化することも可能にしました。そして何より、お客様の成功を支援するために、質の高いコンテンツを開発し、提供するというオーナーシップを共有できるようになったのです。