Docusaurusでマニュアルを作る #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化

フレームワーク Docusaurus Documentation Static Site
読了 4分

#5まで来ると、多言語とバージョンまで備えたドキュメントになります。これで作る段階は終わりました。ドキュメントは一度作って終わりではなく、製品とともに育ち続けるものです。最終回では、そのドキュメントを長く生かしておく運用を扱います。

今回のシリーズはDocusaurusでマニュアルを作る全6回です。

  • #1 インストールから最初のドキュメントまで
  • #2 サイドバーと検索 — ドキュメントの情報構造を組む
  • #3 コンテンツ作成 — コードブロック、Mermaid、admonition
  • #4 Cloudflare Pagesでデプロイしてドメインを接続する
  • #5 多言語とバージョン管理
  • #6 メンテナンス — 検索、アクセシビリティ、ドキュメント文化 ← 今回の記事

今回の記事は検索を付ける、みんなのためのアクセシビリティ、ドキュメントを生かす文化の三つを整理します。

検索を付ける #

#2で先送りにした検索を、ここで仕上げます。二つの道があると述べました。

一つ目はAlgolia DocSearchです。申請して受け取った値をdocusaurus.config.jsのthemeConfigに入れれば終わりです。

docusaurus.config.js — Algolia検索 
themeConfig: {
  algolia: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX',
  },
}

二つ目はローカル検索プラグインです。外部サービスなしでビルド時点にインデックスを作って動作するので、社内ドキュメントや日本語ドキュメントに便利です。

ローカル検索プラグインのインストール 
npm install @easyops-cn/docusaurus-search-local

インストール後にプラグインをdocusaurus.config.jsに登録すると、検索窓が現れます。公開のオープンソースならAlgoliaが、非公開・社内ドキュメントならローカルプラグインが、おおむねよく合います。

みんなのためのアクセシビリティ #

ドキュメントは、できる限り多くの人が読めるべきです。Docusaurusのテーマは基本のアクセシビリティが良好ですが、文章を書く過程で崩れやすい箇所がいくつかあります。

  • 見出しの階層を飛ばしません。一段ずつ下がっていくことで、スクリーンリーダーが構造を正しく読みます。
見出しの階層を守る 
# ページタイトル (h1, ページごとに一つ)
## 大きな節 (h2)
### 小さな節 (h3)
  • リンクテキストは、それ自体で意味が通じる必要があります。「ここをクリック」ではなく「インストールガイド」のように、行き先を記述します。
  • 画像には代替テキストを付けます。ダイアグラムをMermaidで描けばテキストなので、この問題から解放されます。
  • 色のコントラストを守ります。テーマの色をいじるときは、本文と背景のコントラストがWCAG AA基準(4.5:1)を超えるかを確認します。

ドキュメントを生かす文化 #

良いドキュメントツールを備えても、更新が止まればドキュメントはすぐに嘘になります。長く生きているドキュメントの共通点は、ツールではなく習慣です。

核心は、#1で出発点としたDocs as Codeを最後まで守ることです。ドキュメントをコードと同じリポジトリに置き、機能を変えるPull Requestの中で関連ドキュメントも一緒に直します。「ドキュメント更新」を作業完了の条件に入れると、コードとドキュメントが別々に動く事態が減ります。

ここにいくつかを加えます。記事ごとに最終更新日を見せて古い記事を見つけやすくし、壊れたリンクはビルド段階で点検し(Docusaurusは壊れた内部リンクを標準でビルド時に捕まえてくれます)、大きな改編を先送りするより小さく頻繁に直します。完璧な一度の整備より、地道な小さな更新がドキュメントを生かします。

シリーズを締めくくって #

六編にわたって、Docusaurusでドキュメントサイトを最初から運用まで作りました。インストールし(#1)、サイドバーと検索で構造を組み(#2)、コードブロックとadmonitionで内容を埋め(#3)、Cloudflare Pagesでデプロイし(#4)、多言語とバージョンを加え(#5)、最後に長く維持する方法(#6)まで来ました。

ブログが時系列の記事の集まりであるなら、ドキュメントサイトは構造化されたリファレンスです。その違いが、ツールの選択から運用習慣まですべてを分けました。これからは、みなさんのチームのドキュメントをこの流れの上に載せてみてください。

X