メインコンテンツまでスキップ

docStaticの現状に関する技術的評価

· 約6分
Andrew Owen
Andrew Owen
docStatic maintainer

docStaticは、ライターや開発者による寄稿者のニーズに応えるドキュメントソリューションを構築するための、私の2度目の試みです。1度目の試みについては、以前のブログ記事でご紹介しています。あれはコンポーネントの寄せ集めのようなものでしたが、docStaticはそれよりもはるかに緊密に統合されています。もっとも、アーキテクチャ的には、従来の意味でのスタンドアロン製品というわけではありません。 むしろ、Docusaurus（静的サイトジェネレーター）とTinaCMS（Gitを基盤とするヘッドレスCMS）を、厳選し、独自の視点で統合したものです。

主な機能​

  • 主要なコンテンツ形式としてMDX（Markdown + React）を採用。
  • 編集方法：
    • ローカルのテキストエディタ（docs-as-code）を使用し、開発サーバーによる即時再構築が可能。
    • 技術に詳しくないユーザー向けの、TinaCMSのブラウザベースのリッチテキストエディタ。
  • CCMSスタイルの機能（スニペット、条件付きテキスト、変数セット、タクソノミー、用語集）。

開発ワークフロー​

  • Gitが唯一の真実の源（Single Source of Truth）であり続けます。
  • TinaCMSはGitに直接コミットします（またはローカルにファイルを書き込みます）。
  • CI/CDパイプラインと完全に互換性があります。
  • リポジトリ構造はDocusaurusのデフォルトに準拠しており、予期せぬ事態を最小限に抑えます。

事前設定済みの統合機能​

  • OpenAPIドキュメントの生成。
  • Mermaidダイアグラム。
  • KaTeXによる数式レンダリング。
  • Lunrベースの検索。
  • 国際化（i18n）。

スペルチェックや文法チェックのためのLanguageTool連携はサポートされていますが、ブラウザやIDEのプラグインに依存します。

制限事項​

現在、docStaticを採用することは、暗黙的に以下のことを意味します：

  • プラットフォームを自ら管理・拡張すること。
  • ベンダーによる限定的なサポートを受け入れること。

DocStaticは、印刷物やPDF形式のドキュメントを作成する必要があるチームには適していません。また、商用CCMSツールの直接的な代替品でもありません。しかし、市場の大部分においては、すでに機能的に同等のレベルに達しています。

アーキテクチャ​

ワークフロー​

DocStaticは、組み合わせ可能なワークフローを提供します。ステータスはMDXフロントマターメタデータとして実装されています。ステータスはTinaCMSによって読み取られ、カスタムの編集ステータスUIを通じてレンダリングされます。ステータスの遷移はコンテンツネイティブであり、バージョン管理されています。このパターンは、いくつかの商用CCMSベンダーでも採用されています。ただし、その適用は手続き的なものであり、システム的なものではありません。

再利用可能なコンテンツ​

再利用可能なコンテンツは定義された場所に保存され、独立したコンテンツとして管理され、ドキュメント内で参照されます。スニペットはコンテンツオブジェクトです。これはDITAのconrefに非常に似ています。

翻訳とローカライズ​

  • ロケール固有のメタデータが翻訳状態を追跡します。
  • GitHub Actions：
    • 状態の変化を検出します。
    • Slack または Teams への通知をトリガーします。
  • ロケールごとのローカルプレビュー。
  • 翻訳状態は決定論的であり、確認および自動化が可能です。

商用CCMS製品には、ベンダーによる組み込みサポートが含まれています。DocStaticのアプローチは「翻訳運用をコード化する（Translation-Ops-as-Code）」ものです。これは自動機械翻訳を導入する際にはメリットとなりますが、技術的知識のないローカライズチームにとっては、すぐに使える（ターンキー）ソリューションとしては不向きです。

DocStaticとCCMSツールの比較​

DocStaticがサポートするもの：

  • 構造化コンテンツ。
  • 再利用可能なコンテンツオブジェクト。
  • ワークフローの状態。
  • 多言語対応。
  • ダッシュボード（ベータ版）。

DocStaticには以下の機能が欠けています：

  • 一元化されたポリシーの適用。ワークフロールールは、メタデータ、TinaのUIロジック、およびCI/CDパイプライン内に存在します。
  • ロールベースのアクセス制御。ただし、有料のTinaCloudサブスクリプションを利用すれば可能です。
  • 移行ツール。

docStaticとCCMSツールの根本的な違いは、構成可能で検証可能なシステムであるか、それとも組み込み型で不透明なシステムであるかという点にあります。

docStatic：

  • 明示的なメタデータを優先します。
  • 既存のインフラ（Git、CI、Slackなど）を活用します。
  • ターンキー型のUXを犠牲にして、アーキテクチャの明瞭さを優先します。

CCMSツール：

  • すべてを一元管理します。
  • 状態をデータベース内に隠蔽します。
  • 技術的知識のない管理者向けに最適化されています。

docStaticは誰に最適か？​

DocStaticは、エンジニアファーストのCCMSと見なすことができます。透明性の高いGitネイティブの「真実の源」を維持しつつ、作成、再利用、ワークフロー、コンテキストに応じたレビュー（ハイライトやコメント機能を用いたTinaCMS内での非開発者からのフィードバックを含む）を実現します。 オープンなツール、リポジトリ主導のワークフロー、開発者レベルの拡張性を重視しつつ、非開発者によるレビュー機能を犠牲にしたくない場合、docStaticは最適な選択肢となるでしょう。

ロードマップ​

DocStaticは、読者にとって最高のオンラインドキュメント体験を提供することに特化しています。印刷版やPDFはロードマップに含まれておらず、今後追加される可能性も低いでしょう。ただし、オンラインドキュメントにおいてCCMSツールを使用することには、DocStaticに比べて依然として優位性がある2つの分野があります：

  • デプロイの容易さ。
  • ダッシュボード。

ダッシュボードはすでにベータ版として提供されています。デプロイに関しては、npm を使用してデフォルトのリポジトリを作成できるようにすることを目指しています。