Linode におけるDocs as Code

こんにちは！私の名前はネイサンで、私は Linode のテクニカルライティングチームのメンバーです。 私たちの主な仕事の一つはhttps://www.linode.com/docsでガイドやチュートリアルのライブラリの充実に貢献し維持することです。ここでは1,400 以上の記事が公開されています。コンテンツの品質を守り、執筆プロセスでのコラボレーションを促進するために、オーサリングワークフローのdocs as code を出筆手法として採用しました。

Docs as code はドキュメントの作成に使用するツールがソフトウェアの作成に使用されるツールと同じとする手法です。これには次のものが含まれます。

• バージョン管理ソフトウェアの使用　
• プレーンテキストドキュメントファイルの作成　
• 自動テストの実行　
• 継続的インテグレーションと継続的デリバリーの実践　

Linode のテクニカルライティングチームはさらに私たちのドキュメントウェブサイトをホストしているクラウドインフラに対する責任を負うことでこの手法を展開しました。

なぜ Docs as Code ？

これらの慣習に従うとさまざまな利点があります。

• これらのテクノロジを使用すると、テクニカル ライティング チームと Linode の開発チームとエンジニアリングチームとの結びつきが強くなります。
  
• Linode の他のチームも 私たちのプロセスの様々な側面に貢献することができます。たとえば、フロントエンド チームは、既に使用しているツールを活用してドキュメント Web サイトのテーマ/プレゼンテーションを更新するために役立てたり、エンジニアリング チームのメンバーがドキュメント ライブラリの新しい自動テストを作成することが可能です。
  
• 私たちのチームは、自分のプロセスで使用される技術に関するガイドやチュートリアルを頻繁に書いています。これらを自分で実装することで、それらを理解しやすくなり説明する能力が向上します。
  
• また、Linode の製品を正確に文書化する必要があります。これには Linode のコードベースのレビューを伴う可能性があります。 これらのプロジェクトに使用される言語やツールへの精通は、それらをより深く理解するのに役立ちます。

当社の実装　

この手法の実装は組織によって異なるため、プロセスの詳細な概要を説明します。

1. 作成:当社のテクニカルライターは、Markdownで新しいガイドブックを作成します。Markdown はプレーンテキスト ファイル内のリッチ テキストを表すために使用され、さまざまなツールで HTML にコンパイルできます。Markdownはソフトウェア開発においてほぼ一般的に採用されています。たとえば、GitHub README ファイルはMarkdownで書かれています。Markdown で記述すると、Visual Studio Code などの最新のデスクトップ エディターから Emacs や Vim まで、任意のプレーンテキスト エディターが使用できます。私たちは人々が自分の好みのテキストエディタについて強い思いを持っていることを知っており、この柔軟性はより多くの人々が私たちのライブラリに貢献するのに役立ちます。
   
2. ローカル サイトのプレビュー:　 私たちのライブラリ内の Markdownファイルは、最終的なHTMLに スタティックサイトジェネレーターを使って生成されます。静的サイトとは、要求されたときにレンダリングするためのデータベースに依存しない、事前に構築されたページのコレクションです (WordPress のような CMS の場合と同様)。このため静的サイトの読み込みは非常に高速です。スタティックサイト ジェネレータは、コンテンツ ファイル (Markdown など) と指定したテーマを組み合わせて静的サイトをレンダリングします。
   
   Linode のドキュメント Web サイトでは Hugoが使われており、それは 最も人気のあるスタティックサイト ジェネレータの一つです:
   
   • Hugo は、多くのOS上で十分に文書化されたインストール方法を提供するため、新しい従業員が加入した際に問題ありません。
     
   • Hugo にはローカル開発 Web サーバーが含まれているため、作成者は新しいガイドを出筆しながらサイトを自分のコンピュータでレンダリングできます。このサーバーは作成者がファイルを保存するたびに動的にリロードを行ないます。
     
   • Hugoは非常に高速で、それは私たちの規模のライブラリにとって意味のある事です - 私のMacbook Proは約3秒で1400全てのガイドをコンパイルすることができ、動的なリロードはほぼ瞬時で行われます。 
     
   • Hugo のshortcodesは強調表示されたノートや行番号付きコードスニペットなど、Markdown にはない機能を備えたガイドの充実にも役立ちます。
     
     
3. コラボレーション:ドキュメント ライブラリはGitHub でホストされているパブリック Git リポジトリに格納され、各作成者はこのリポジトリのフォークを管理します。作成者がガイドの作成を完了すると、変更をコミットし変更をフォークにプッシュアップしてから、メイン リポジトリに対してプル要求を開きます。
   
   私たちのライティングプロセスには、2人の別々のチームメンバーが技術的な編集を行い、新しいガイドやガイドの更新にコピー編集を行います。これらのチーム メンバーは、プル要求の分岐をダウンロードし、変更を行ってコミットし、GitHub のブランチにプッシュアップします。Git は開発に近いもう 1 つのツールであり、これを使用することでgitflowワークフローなどの共同作業に関するいくつかの標準的なベスト プラクティスを活用できます。
   
   また、GitHub の人気は、多数の便利なインテグレーションが行われていることを意味します。我々は特にNetlifyを使用して、プル要求ごとにパブリックにアクセス可能な自動プレビューを生成します。私たちはしばしば異なる部門のLinodianからのフィードバックを求める必要があり、彼らは私たちのドキュメントリポジトリを複製し、彼らのラップトップに Hugo をインストールすることなく、これらの共有可能なNetlifyリンクを表示することができます。
   
   最後に、パブリック リポジトリでホストすると、ライブラリが外部の貢献者に公開されます。
   
4. テストの様子。 プル要求が送信または更新されるたびに、PR のコンテンツに対して一連のテストが実行されます。これらのテストは、 Travis CIを使って行われ、それは GitHub インテグレーションも提供する継続的なインテグレーションサービスです。これらのテストのいずれかが失敗した場合、プル要求はマージされるのを一時的にブロックされます。
   
   • ガイドコンテンツはスペルとスタイル(専門用語の適切な大文字と小文字など)がチェックされます。私たちはこれらのタスクを実行するために、散文で動作するように設計されたオープンソースのリンターであるValeを使用しています。私たちが最初にValeをインテグレートしたとき、私たちのライブラリで500,000以上のスペルミスを報告しました。恥ずかしい話でしたが、この数字を知って対応できたことは、私たちのコンテンツと新しいパブリッシングシステムに対する自信を大きく高めました。
     
   • Web サイトからコンテンツをスクラップするオープンソースの Python フレームワークである Scrapyを使用して、ガイド間で潜在的な壊れているリンクをチェックします。このテストは Linode のエンジニアリングチームのメンバーと共同で作成されました。Scrapy を最初に実装したときも、同様に修正が必要な多数の壊れたリンクが見つかりました。
     
   • もう一つの Python スクリプトは、ガイドのフロントマターメタデータが有効であり構文エラーがないことをチェックします。フロントマターセクションが壊れていると、サイトの構築時に問題が発生する可能性があるため、この検証を行うと本番 Web サーバーの更新時にサイトが確実にレンダリングされることを確認できます。
     
5. 公開とホスティング:　 ドキュメント Web サイトの更新は、GitHub の特定のイベントからトリガーされるスクリプトのコレクションによって自動的に処理されます。　
   
   • コンテンツがメインドキュメントリポジトリのマスターブランチにマージされるたびに、webhook通知がLinodeステージング Web サーバに送信されます。このステージング Web サーバーは、GitHub からマスターブランチを取得し、レンダリングされたサイトのターゲットとして Web サーバーのドキュメントルートをもとに、Hugo を使用してサイトを構築します。このステージング サイトを表示し、コンテンツが期待どおりに表示されることを確認します。
     
     ステージング サーバーは、最初はワークフローの一部ではありませんでした。これは、あるインシデント発生時、本番サイトの更新中にCSS/スタイリングが一時的に壊れてしまった事態後に構築されました。要するに、Netlify は新しいサイトリリースのプレビューを正しくレンダリングしましたが、スタイルの問題をキャッチできませんでした。これは、私たちの「プロダクション」ビルドパイプライン(CSSやその他の資産を縮小する)の代わりに「開発」ビルドパイプラインを使用したためです。新しいステージング サーバーは運用サーバーと同じ構成で設定されるため、運用ビルド パイプラインも使用するため、このようなエラーがキャッチされます。
     
   • 運用サイトを更新するには、GitHub で新しいリリース タグを作成します。これにより運用 Web サーバーに送信される別の webhook 通知がトリガーされます。このサーバーはステージング サーバーと同様のスクリプトを実行しますが、代わりに新しいリリース タグからコンテンツをプルダウンします。
   • 自動発行機能を使用すると、このプロセスを手動で実行した場合に発生する可能性のある人為的なエラーを最小限に抑えることができます。ステージング サーバーと運用サーバーはどちらもSalt式による構成管理下にあり、こちらもソフトウェアのメンテナンスや更新が必要な場合の人為的なエラーを最小限に抑えることができます。Saltは Linode の他のインフラプロジェクトにおいても使用されており、ドキュメントのウェブサーバーはフリートの他の部分と一緒に管理することができます。

この手法を採用することで、ワークフローを大幅に合理化する事ができましたが、常に反復処理と改善に取り組んでいます。私たちが行うことができる提案がある場合は私たちにお知らせください！私は他のチームメンバーと共に、Write the Docs Slackにnmelehanとして書いています。Docs as Codeについて詳細を読みたい場合は、Write the Docs サイトに掲載されているEric Holscher's guideをお勧めします。