先週ドキュメンテーションサイトが大幅に変更されたことにお気づきでしょうか?まだご覧になっていないのであれば、今すぐ確認してみてください。一見の価値ありです!

数ヶ月の作業を終え、Nuxeoドキュメンテーションサイトが新たに生まれ変わったことをお知らせでき、喜びに堪えません!

ビフォー
Old Documentation Site

アフター
New Documentation Site

外観やイメージをアップデートしただけではありません。Metalsmithで静的サイトを生成するためにConfluenceを廃止して、ドキュメンテーションツール自体を変更しました。今回は、なぜ移行させる決断をし、どのようにしてMetalsmithプラグインエコシステムを改良させたのか、説明いたします。

Metalsmith静的サイト生成とは何か?

新しいドキュメンテーションWebサイトは、期待されるルック・アンド・フィールとリンクを生成するためのパイプ化された変換プロセスを経るテキストコンテンツとグラフィカルリソースから構成されています。MetalsmithはJavaScriptのパイプロジックを処理します。たとえば、指定ページへ移動する期待リンクによって{page page='my-page' space='NXDOC'}をすべて置き換えるパイプを追加することが可能です。WebサイトのソースはGitHubにコミットされています。

なぜConfluenceを廃止し、Metalsmithで何を得たのか?

Confluenceは、ドキュメンテーションサイトを立ち上げる際のすばらしいツールでした。ページの使用、作成、更新、保守は非常に簡単でした。しかし、数カ月間にわたっていくつかの限界に直面し、最終的に移行を決定しました。以下がその理由です。

  • ドキュメントの全体的なレイアウトの管理を強化:
    まず緊急に必要なことは、同じスペースにないときでも同じバージョンでないときでも、ページ間のナビゲーションを向上させるために、より軽量で反応性の高いWebサイトでドキュメントを簡素化することでした。Confluenceはテンプレート調整機能をある程度提供しましたが、それはかなり専有技術によるものでした。そのため、デリバリーを必要とし、毎回バージョンの移行に負担がかかりました。

  • さまざまなバージョンの製品で同じページをリンクするコントロール改善:
    Nuxeo Platformの主要バージョンは毎年リリースされています。特定のバージョンのドキュメント全体を閲覧することは可能ですが、同じページから前のバージョンの関連コンテンツを参照することも役に立ちます。古いドキュメントサイトではこれを簡単に行う方法はありませんでした。現在は、自動リンク生成で簡単に実装できるようになりました。また、関連するページがない場合やコンセプトが変更された場合に、フォールバックリンクを追加することもできます。

  • SEOの動作:
    ページのHTMLコンテンツを完全に管理できるため、当社には決定的に重要な検索エンジンの最適化に必要なヘッダーをすべて簡単に提供することができます。これは以前は不可能でした。

  • 優れたオーサリングエクスペリエンス(ネイティブのマークダウンサポートと優れたコンテンツエディタによるページコンテンツのコントロールの向上):
    マークダウンはConfluenceの拡張機能を使って追加することができますが、以前はそうではありませんでした。Confluence wikiの構文はかなり専有技術的ですが、ドキュメントを書く開発者には魅力的ではありません。簡単なマークダウンページでは、もう「htmlソース」に切り替える必要はありません!さらに、Atom.ioやSublimeを使ってコンテンツを書くのが、もっと快適になりました。新しいサイトは本質的にテキストファイルのフォルダで、オフラインで編集したり、一括検索を実行したり、一度にすべてのファイルを置き換えたりすることができます。

  • プロセス管理と品質チェックの向上:
    レビューの日付やページの状態など、プロセスを管理する機能の実装を開始しました。品質チェック(ページ構文、途切れたリンクなど)の追加は、非常に簡単です。チェック機能がかなり増え、今後もさらに追加される計画です。

  • Githubのコラボレーションフローは素晴らしい:
    それぞれの変更、プルリクエスト、コミットの履歴などのためにブランチを持つことができるのは本当にクールです。

Bare Metalsmith Generatorに追加された機能

Metalsmithのドキュメントを読むことで、Metalsmithのすべてがプラグインによって処理されることがすぐにわかります。Confluenceのうち残しておきたい機能をすべて列挙し、それぞれのプラグインを作成しました。例:

  • 抜粋
  • 複数抜粋
  • タグ
  • 履歴
  • ページリンク
  • 左メニュー
  • ページレビュー警告
  • ページリンク

また、Confluenceにはなかった新しいプラグインも作成しました。たとえば、バージョン管理では、2つのバージョン間で名前が変更されたとしてもページをリンクできます。また、文書レビュープロセスも実装しました。

何よりも、MetalsmithによるドキュメンテーションWebサイトでは、コンテンツ、レイアウト、グラフィックデザイン、投稿を進化させることができる余地が残されています。

コンテンツの移行

ConfluenceのRest APIを使用してコンテンツを移行し、そのコンテンツをマークダウンに変換するために変換を適用しました。また、(短いリンク、履歴の概要、最後の作成者、タグなどを得ることを含め、)無駄な部分をすべて取り除きました。

次に必要なこと

これは、プロジェクトの手始めにすぎません。すでにナビゲーション、グラフィック、デザインの改良を加えて、ドキュメンテーションWebサイトの第2バージョンに取り組んでいます。Nuxeoは急速に普及しているため、絶えず進化するニーズに合わせてドキュメントを拡張する必要があります。

Nuxeoとの出会いを契機として、当社の製品について学び、より多くのドキュメントを理解し、それを人に伝えることによって、皆さんの人生がより快適になることを願っています。この新しいWebサイトに関するご意見やご感想をお知らせください。

最後に、当社が作成しているMetalsmithプラグインのご利用にご興味がおありなら、GitHubをご覧ください。)皆さんのご意見や改善点の提案をお待ちしています。さらにリリースが続きますので、今後の進展にご注目ください!