操作マニュアルをMarkdownで書くMarpでスライド/PDF化する

問題設定：マニュアルは、なぜ差分が取れないのか

システムの操作マニュアルを、長らくWordやPowerPointで作ってきた。書き味は悪くない。だが運用に回すと、じわじわと効いてくる不満がある。まず、バイナリ形式なので差分が取れない。「前回からどこを直したのか」を知るには、旧版と並べて目で追うしかない。次に、見た目の統一が属人的になる。フォント、余白、見出しの色。担当者が変わるたびに微妙にずれ、気づけばマニュアルごとに顔つきが違う。そして極めつけは、テンプレートを一箇所直しても、既存の全ファイルには反映されないことだ。見た目を変えたければ、全ファイルを開いて手で直して回ることになる。

これはコードで言えば、バージョン管理もされず、共通コンポーネントもなく、コピペで増殖したソースを保守している状態に近い。ならば逆に問うてみたい。ドキュメントを、コードと同じ規律で扱えないのか。差分が取れて、見た目は一元管理され、出力はビルドで再現される。そういう運用にできないか。

選んだ形：ソースはMarkdown、見た目はテーマCSS、出力はMarp

答えはシンプルだった。マニュアルの本文はMarkdownで書く。プレーンテキストなので、そのままバージョン管理に乗る。差分は行単位で取れるし、レビューもコードと同じ流儀でできる。そしてMarkdownをスライドやPDFに変換するツールとしてMarpを使う。各マニュアルの先頭には、共通のテーマを指定するfrontmatterを一行置くだけだ。

---
marp: true
theme: manual
paginate: true
---

# 操作マニュアル

内容はここから普通のMarkdownで書いていく。

肝はtheme: manualの一行にある。フォントも余白も配色も、見た目に関わる定義はすべて共通のテーマCSS一枚に集約してある。全マニュアルがそれを参照するので、ブランドカラーを変えたくなったらCSSを一箇所直すだけでいい。次にPDFを書き出したとき、全マニュアルの見た目が揃って更新される。手で全ファイルを開いて回る作業は消える。

レイアウトのパターンも、CSSのクラスとして定義しておく。通常の一段組み、左右の2カラム、画像を大きく配置する版。書き手は本文側でクラス名を指定するだけで、決められた型に収まる。

<!-- _class: two-column -->

左カラムの説明。

右カラムの補足。

ここでひとつ、実務のポイントがある。Marpのレンダラでは、本文中にインラインでstyle="display:flex"のように書いても、一部のスタイルは期待どおりに効かない。だからレイアウトは本文側でその都度組むのではなく、必ずテーマCSS側のクラスとして定義しておく。書き手は_class:でそれを呼ぶだけ。見た目のロジックがテーマに寄るほど、本文は内容だけに専念できる。

出力はコマンド一発、執筆中はプレビューで

PDF化はコマンドひとつで済む。テーマを指定し、PDFとして書き出し、見出しからアウトライン(しおり)を付ける。

marp manual.md --theme manual.css --pdf --pdf-outlines -o manual.pdf

一度この形にすると、出力は完全に再現可能になる。同じソースと同じテーマからは、いつ誰がビルドしても同じPDFが出る。ドキュメントの「ビルド」だ。書き出したPDFはそのまま配布したり、システム側に添付して掲載したりする。

執筆中の体験も地味に効く。エディタにテーマを登録しておくと、書いている最中からプレビューに仕上がりが映る。PDF化して初めて崩れに気づく、という手戻りがなくなる。書きながら完成形が見えるので、書き手は内容の吟味に集中できる。

AIとの協働作業での学び：ドキュメントも「ソース・テーマ・ビルド」で保守する

やっていることを煎じ詰めると、コードで当たり前になった規律を、そのままドキュメントに持ち込んだだけだ。ソースはプレーンテキストにする。見た目はテーマで一元管理する。出力はビルドで再現する。この三つを守ると、ドキュメントも差分・再現性・一貫性という同じ土俵に乗る。

面白いのは、これが道具を増やす話ではないことだ。むしろ普段書いているMarkdownと、普段叩いているコマンドの延長でしかない。新しい編集ソフトの使い方を覚える必要はなく、書く人はひたすら内容に集中できる。ちなみに、いま読まれているこのブログ自体も、Markdownで書いてビルドで静的化している。文章という成果物を、コードと同じ流儀で扱う。マニュアルもブログも、根っこは同じ発想の上に立っている。