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

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

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

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

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

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

検索を整える #

#2で見たように、Materialの検索は内蔵なので別途付けるものはありません。ただし、読者の体験をさらに引き上げる機能をいくつかtheme.featuresでオンにできます。

mkdocs.yml — 検索強化 
theme:
  name: material
  features:
    - search.suggest     # 入力中のオートコンプリート
    - search.highlight    # 結果での検索語ハイライト
    - search.share        # 検索結果リンクの共有

検索はビルド時点でインデックスを作ってブラウザで動く方式なので、サーバーが要りません。日本語の分割が物足りなければ、#2で扱ったseparatorの調整を併せて適用すればよいです。

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

ドキュメントは、できるだけ多くの人が読めるものであるべきです。Materialはデフォルトのアクセシビリティが良好ですが、記事を書く過程で壊れやすい箇所がいくつかあります。

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

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

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

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

ここに実用的な工夫をいくつか足します。記事ごとに最終更新日を表示して古い記事を見つけやすくし(Materialのgit-revision-dateプラグインが自動で付けてくれます)、壊れたリンクはビルド段階でチェックし、大きな改編を先延ばしにするより小さく頻繁に直します。完璧な一度の整備よりも、地道な小さな更新がドキュメントを生かします。

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

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

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

X