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

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

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

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

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

検索は手を加えるところがない #

#2で見たとおり、Starlightの検索はPagefindを標準で組み込んでいます。他のツールが検索を別途付けたり、分かち書きを手直ししたりしなければならなかったのと異なり、Starlightはビルドするだけで検索が動作し、韓国語を含む複数の言語も問題なく処理します。運用の観点で最も気を使うことが少ない部分です。

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

ドキュメントはできる限り多くの人が読めるべきです。Starlightはアクセシビリティを重視しデフォルト値が堅実ですが、記事を書く過程で壊れやすい箇所がいくつかあります。

• 見出しの階層を飛ばしません。一段ずつ下がってこそ、スクリーンリーダーが構造を正しく読み取ります。

# ページタイトル (h1, ページごとに一つ)
## 大きな節 (h2)
### 小さな節 (h3)

• リンクテキストは、それ自体で意味が通らなければなりません。「ここをクリック」ではなく「インストールガイド」のように行き先を書きます。
• 画像には代替テキストを付けます。ダイアグラムをMermaidで描くとテキストなので、この問題から自由になります。
• 色のコントラストを守ります。テーマ色を手直しするときは、本文と背景のコントラストがWCAG AA基準(4.5:1)を超えるか確認します。

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

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

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

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

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

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

これでHugo・MkDocs・Docusaurus・Starlightの四つのツールをすべて同じ流れで扱いました。どのツールが自分のチームに合うかはドキュメントサイトジェネレーター比較の記事に整理してありますので、選択に迷うならその記事から読んでみてください。ぜひこの流れを土台に、皆さんのチームのドキュメントを作り始めてみてください。