オープンソースによるNew Relicドキュメントの強化

3/1にNew Relicのドキュメントサイトが刷新され、静的ファイルベースで高速化し、加えてもとの文書がGitHubにて公開されています。なぜオープンソース化したのか、どのような技術で実現したのか、そして今後向かっていく姿について、Enhancing New Relic Docs—the Open Source Wayの抄訳にてお伝えします。また、日本語翻訳部分に関してもissueにてフィードバックを受け付けております。詳しくは文末をご覧ください。

計装用のエージェントやPixie Coreソフトウェアののオープンソース化に加えて、オープンソースプロジェクトやイニシアティブを作成したことやNew Relic Oneアプリケーションの開発を可能にしたことまで、New Relicのテクノロジーの多くがオープンソース化されています。つまり、New Relicは、オープンな交流、共同作業への参加、高速プロトタイピング、透明性、業績主義、コミュニティ指向の開発の原則を受け入れ、それを称えています。そして私たちはオープンソースコミュニティに貢献するにはどうしたらよいかを常に考え続けています。

そこで今日、私たちは docs.newrelic.com をオープンソースとして公開します。すべてのNew Relicユーザーのために、issueを提出したり、ドキュメントを編集したり、ドキュメントをもっとより親切にしたりできるようになりました。

ドキュメントをオープンソース化する理由

当社のドキュメントは、当社の製品とユーザーエクスペリエンスに欠かせないものです。私たちはそのドキュメントを業界で最高のものにしたいと考えています。もし当社のコードに貢献していただけるのであれば、当社のドキュメントにも貢献していただく必要があります。そして今日できるようになりました。

しかし私たちがコードを扱うのと同じようにドキュメントを扱うだけではありません。ドキュメントは特にオープンな編集に適しています。当社のドキュメントは以前からRelics（New Relicの社員）であればだれでも編集できるようになっていました。製品チームが新機能や機能、メリットを提供する間に、昨年は400人以上のRelicsがドキュメントを最新の状態に保つために協力してくれました。

昨年の読者アンケートでは50%以上の方がドキュメントの編集に興味があると回答し、70%の方がissueの提出を希望していると回答しています。

オープンなドキュメントと熱心なユーザーコミュニティを持つことは、New Relicを利用するすべての人にとって、恩恵を受けることができる素晴らしいことです。

• オープンで直接的なコラボレーション
• ドキュメントの正確性と完全性の向上
• ドキュメント内の問題や不一致を報告するための簡単なフィードバックループ
• オープンソースコードをサポートするオープンソースドキュメント

新たな挑戦に向けてのアーキテクチャ変更

Drupal 7 プラットフォームからドキュメントを移行するのは簡単な作業ではありませんでした。確かにもっと大規模なドキュメントサイトはありますが、私たちのサイトの規模でも手動での移行を困難にするほどの大きさです。私たちのサイトには5,863個のユニークなコンテンツが含まれています。この規模のサイトにおいて、移行を自動化し、何千ものリンクやリダイレクトが壊れていないことを確認する必要がありました。

この大規模な作業を達成するために、私たちはオープンソースのソリューションに目を向けました。新しいドキュメントサイトは、Gatsby.jsとGraphQLを使ったJAMstackアーキテクチャの静的サイトとして構築しました。静的なサイトにすることで、GitHubネイティブな（データベースやウェブアプリを管理する必要がない）実装が可能になりました。

レスポンシブで柔軟性のあるサイトにするために、ReactやEmotion CSSなどのJavaScriptオープンソースプロジェクトを活用しました。また、グローバルコンポーネントライブラリとdev.newrelic.comとopensource.newrelic.comで使用したGatsby Themeを使ってサイトを構築しました。これにより、バナーによる告知やローカリゼーションツールなどのUI機能をこれらのサイト間で簡単に共有することができ、同じNew Relicファミリーの一部として表示されるようになりました。

GatsbyのGraphQL APIを使用すると、任意のページのコンテンツを簡単に照会することができます。私たちはこのAPIを利用して、ドキュメントのコンテンツをプラットフォームのUIやその先へ共有しています。例えば「What's New」はドキュメントサイトに記述されており、公開されたドキュメントとNew Relic One UIの両方に自動的に公開されます。同様に、当社の「data dictionary」のコンテンツはドキュメントサイトやNew Relic OneのクエリビルダーそしてGraphQLを介して利用できます。APIを利用することで、ドキュメントサイト内で自動的にインデックスページを生成することが容易になり、ライターの労力を軽減することができます。

ローカライゼーションは当社の最優先事項です。私たちは世界中で新しいユーザーをサポートし、成長しています。そのため、日本語などの他言語にも柔軟に対応できるようにコンポーネントやページを構築しました。これでグローバルな成長にも対応できるようになりました。

サイトの更新を簡単にするために、GitHub ActionsとAmazon Amplifyを使ってビルドとデプロイのプロセスを最適化しました。デプロイを自動化するだけでなく、Amplify のプレビューでは PR からすぐに変更点をテストしてデプロイできるようになりました。これにより、ドキュメントチームはコンテンツのメンテナンスや更新をより簡単に行えるようになりました。

データ形式の選定

初期の頃からMarkdown コンテンツに JSX を記述するために MDX を選択しました。このアプローチにより、折りたたみ可能なリスト、コードの強調表示、複雑なテーブルなどの気の利いたライティングツールを維持しながら、読みやすく編集しやすいソース・コードを維持することができます。各ドキュメントはまた、タイトル、SEOメタデータ、リダイレクトなどのデータのためのシンプルなfrontmatterを持っています。

Codemods を使用して、既存の HTML を取得しMDX 内の Markdown とカスタムコンポーネントの組み合わせに変換しました。codemodsは、5,863個のコンテンツの新しいサイトへの移行を人の手を介さずに自動化する立役者でもありました。何千ものページを変換したにもかかわらず、スクリプト全体がわずか2～3分で実行されました。

サイトナビゲーションを定義するために、JSONよりもYAMLを選択しました。このおかげで、コンテンツのコントリビューターがドキュメントを追加し、それらを移動することでカテゴリにどのような影響を与えるかを視覚化することが容易になりました。

data dictionaryやWhat's NewなどのサービスにJSONエンドポイントを提供ています。JSONのより構造化されたデータ形式は、UIサービスがコンテンツを利用して変換することを容易にします。また、JSON を使用してドキュメントからメタデータを引き出し、新しい右サイドのナビゲーションに関連リソースリンクを追加できます。

ドキュメントのオープンソース化の次は何ですか？

私たちの新しいアーキテクチャは、私たちのドキュメントを構築し充実させるための柔軟な基盤を提供しています。新しいサイトはまだ立ち上がったばかりですが、当社のエンジニアたちはすでに新しい可能性に挑戦し、イノベーションを起こそうとしています。私たちは「イノベーションの日」と呼んでいる時間を確保し、私たちの優秀で抑えきれない開発者たちはインタラクティブなサンドボックス、GraphQLとRESTエクスプローラのサイトへの統合、ドキュメントの訪問者にデータをインラインで表示できるようにするための認証など、興奮させられる可能性を示してくれました。

ドキュメントをより良いものにするためのアイデアがあれば、GitHub にissueを提出して、私たちに知らせてください。

チーム間の共同作業

このプロジェクトの楽しみの一つは、ライターとエンジニアが協力して物事を成し遂げる様子を見ることでした。ライターはライティングの専門知識と、ユーザーがどのようにNew Relicを利用しているかについての深い洞察力を持っていました。エンジニアは技術的な洞察力と、開発者としてNew Relicのドキュメントを使用する際の実体験を持ってきてくれました。

それが相まって楽しい雰囲気を醸し出していました。ほぼ毎日のようにライターがプレビューサイトを訪れたり、アイデアや問題をSlackで開発チームに送信したり、数分後には開発チームから解決策や反論が返ってくるのを目の当たりにしました。このプロジェクトの成功を保証してくれたのは、ドキュメントチームとデベロッパーイネーブルメントチーム、そしてこの記事の共著者であるプロダクト マネージャーのJohn Vajdaです。

ぜひ参加してください

毎日オープンソースプロジェクトに取り組んでいるすべての人々や組織に心から感謝しています。私たちは皆さんとパートナーを組むのを待ちきれません。私たちはオープンソースの方法で生活できるように、パブリックソフトウェア企業がオープンでできることの限界を押し広げていきたいと思っています。

新しいドキュメントサイトをチェックしてください。次に、README ファイルを見て、issueを提出したり、編集したり、コントリビューターの資料に飛び込んだりして、参加してください。皆様からのご連絡をお待ちしています。

[追記] 日本語翻訳について問題を見つけた場合、ぜひissueにて問題点をお知らせください。フィードバックいただいた問題点に取り組んで日本語訳の改善に努めます。日本語翻訳部分についてはGitHubのPRを直接取り込む準備ができていないため、PRを頂いても対応することができないことをご了承ください。