説明書
いまどきの「製品」説明書は、製本を前提にしない。Web 形式にして、さまざまなフロントエンドフレームワークの技術を使えば、読みやすさも検索のしやすさも非常に良いものにできる。
一方、従来型の説明書は、製本と PDF の閲覧体験の両方を考慮しないといけない。たいていの会社では Word で書いて PDF に書き出し、印刷・製本に使っている。
この方法では、文書全体の書式を管理するのがとても難しい。いわゆるテンプレート文書はあるが、私の執筆経験からしても、頻繁に書式を調整したり、書式コピーを使ったり、ページを追加するたびにヘッダーとフッターを直したりしなければならない。
Word はとても賢く、いろいろ自動で処理してくれる。しかし時々、余計なことをしてくれる。Office のベストプラクティスを学ぶ気はまったくない。それでも製品説明書の一部は、開発が書かざるを得ない。
もちろん、私が内容を書くだけで、書式調整は他の人に任せることもできる。自分で調整するなら、執筆時間が20分遅くなるだけで済むかもしれない。だが他の人に頼むと、相手は1時間かけて慎重に確認しなければならず、ミスも起きやすい。
私は、Markdown を書くように内容に集中するだけで、決まった書式の文書を生成してくれるツール・フレームワークを探し続けていた。候補は多いが、どれも満足できなかった。組版が製本を考慮しにくい、出力される PDF にしおりが付かない、Markdown 方言のタグが多すぎる、といった理由だ。
昨日、quarkdown の新バージョンが公開されたのを見て、2年の発展を経て、自分のニーズを本当に満たせるようになったのか確かめてみたくなった。それがだんだん、さまざまなドキュメントフレームワークを徹底的に選定し試す流れになった。
最終的に選んだのは Pandoc + LaTeX だ。実は2年前にこの作業を始めようとしたときも、調べると同じ構成が推奨されていた。「LaTeX で本当の組版をしよう！」と思ったが、当時の私は LaTeX の記法をまったく知らなかった。2年前は AI もプロジェクトの土台をまともに構築できなかったが、今ならできる。
執筆体験
このフレームワークなら、本当に Markdown だけで内容を作り上げることができる。レイアウトに関することは一切考えなくてよい。
- 章や節は、Markdown の見出しレベルに従って自動で番号が付く。
- 目次は章や節から自動生成され、含める範囲の見出しレベル（1〜n）も調整できる。
- 画像には自動で番号が付く。
- 生成される PDF にはきちんとしおりが付く。
- 余白はすべて一括で調整でき、製本にも優しい。
- Markdown はほぼプレーンテキストで、画像を別ファイルに分けて保存できるので、バージョン管理がしやすい。
生成される PDF の一例
出力結果
その他の機能
プロ向けの組版フレームワークである LaTeX は、もちろん 透かし や 背景 といった高度なエフェクトにも対応している。ただし汎用的な機能ではないので、自分で GPT に聞いてみてください。