はじめに
本記事は、OPTiM TECH BLOG Advent Calendar 2025 Day 17 の記事です！
こんにちは！ソリューション開発部の麥です。医療ユニットに配属された25新卒で、普段はOPTiM AIホスピタルの開発をしています。
今回は、OPTiM AIホスピタルのマニュアル作成で直面した課題と、それをMarkdown形式とAIを組み合わせてどのように解決したのかをご紹介します。
従来の方法でマニュアルを作成
マニュアル作成というと、NotionやMicrosoft Wordを思い浮かべる方が多いのではないでしょうか。実際、当社の製品マニュアルの多くもNotionやWordで作成されています。
最初、Notionを使うことを考えていましたが、私たちのチームが開発しているOPTiM AIホスピタルは病院向けの製品です。病院という特殊な環境では、インターネット接続が制限されている場合もあり、Webマニュアルだけでなく、紙媒体配布を想定したPDFマニュアルが必須となります。
そこで、Wordでのマニュアル作成を試みました。ところが、実際の運用を始まってから、以下のような課題が次々と発生しました。
画像の配置やスタイル編集は手動修正が必須
画像管理が予想以上に煩雑です。画像の配置が不安定で突然ずれ、サイズ調整や位置合わせに多大な時間が費やされます。さらに、強調用の赤枠や矢印の追加も手作業が必要となり、AIが自動で調整できない部分が大量に発生してしまいます。
AIに完全に任せることができず、手動で修正する箇所が多く残る
フォントや文字サイズの統一が難しく、複数人での編集時にはフォーマットが崩れやすくなります。つまり、AIが生成したマニュアルを使用できるレベルに仕上げるまで、多くの手動修正が必要となり、AI活用による工数削減効果が限定的になってしまいます。
レビュー・管理するのが難しい
変更箇所の特定が難しく、バージョン管理も複雑です。共同編集時の整合性確保も大変であり、AIが修正した内容を正確に追跡することが困難になります。
さらに、完成したPDFマニュアルには、Webマニュアルと比較して検索機能が限定的であり、閲覧性にも課題がありました。
解決策：Markdownという選択
Markdownとは、シンプルな記法で文書を作成できる軽量マークアップ言語です。技術文書やブログ記事の作成によく使用され、GitHubなどでも標準的に採用されています。
大きな特徴としてはシンプルな記法にあります。
- 見出しは
#の数で階層を表現 - 強調は
*や**で囲む - 箇条書きは
-や数字 - コードブロックは
```で囲む
このような直感的な記法により、
- 書式を意識することなく文章作成に集中できる
- AIが自動生成・修正しやすい（テキストベースなので）
- バージョン管理ツール（Git）での差分追跡が容易
- 複数の出力形式への自動変換が可能
Markdownマニュアルの道
私たちのチームで求められる形式はWebマニュアルとPDFマニュアルです。 Markdownを活用することで、この両方に効率的に対応できます。
ベースのMarkdownファイル
まず初めに、効率的な管理のためのディレクトリ構造を設計します。私たちのチームでは、以下の図のような構成を採用しました。
このような構成にすることで、マニュアルの内容を論理的な単位で分割して管理できます。また、ファイル名に連番を付けることで、セクションの順序を明確に保つことができます。画像ファイルは各セクションのassetsフォルダーで管理することで、関連資料の整理も簡単になります。
マニュアルの本文は、通常のMarkdown記法で記述します。見出しには#を使用し、必要に応じて箇条書きやテーブルなども活用できます。シンプルな記法なので、エンジニアでなくても簡単に習得できる点が特徴です。
HTML化
HTMLファイルへの変換には、Mkdocsというツールを採用しています。Pythonがインストールされている環境であれば、簡単に導入できます。
Mkdocsプロジェクトの中心となるのはmkdocs.ymlというファイルです。このファイルでサイトのタイトルやテーマ、必要な拡張機能などを設定できます。
また、各ディレクトリに .pages ファイルを作成することで、セクションの見出しやファイルの並び順をカスタマイズできます。これにより、マニュアルの構造をより見やすく整理することが可能です。
なお、ZensicalがMkDocsの後継となっているため、将来的にはZensicalへの移行を検討中です。
PDF化
PDF変換のプロセスは少し複雑ですが、段階的に進めることで確実に実現できます。
まず最初に、散らばっているMarkdownファイルを1つのファイルに統合する必要があります。これにはコマンドを使って、Markdownを結合します。
find docs -type f | grep -E -v "pages|index.md|.png|.css" | sort | xargs -I {} sh -c 'cat "{}"; echo ""' > ./dist/manual.md
ファイル名は連番で管理しているので、sortを使用すれば順番の乱れも心配ないです。
そして画像もこちらのコマンドで1つのフォルダーにまとめます。
find docs -type f | grep "drawio.png" | xargs -I {} cp {} ./assets/
こうすることで、長い長いMarkdownファイルの出来上がりです。文章内の画像のパスも変更ありませんので、画像の参照もぱっちりです。
次に、MarkdownファイルにPandocをかけてHTMLに変換します。
Pandocは、Markdown、Word、HTML、PDFなど様々な文書フォーマット間で相互に変換できる文書変換ツールです。入出力のフォーマットを指定することでフォーマットの崩れが少なく、さらに豊富なプラグインにより好みのスタイルを柔軟に応用できる特徴があります。これらの理由から、今回はPandocを採用しました。
pandoc -d pandoc_html.yml --lua-filter pagebreak.lua -c main.css
改ページのオプションを追加し、またHTMLですので、好みのCSSを編集し適用することもできます。
当社のデザインガイドラインに沿って、CSSを作成しました。 次のようなHTMLファイルになりました。
表紙と目次はまだありありませんが、CSSが適用され、見やすいマニュアルの雛形になりました。
ここまで長い道のりでした。いよいよPDF化です。 ここではPythonコマンドを動かして次のことを行います。
- 既に用意している表紙が含まれたHTMLファイルを結合する
- 目次をHTMLをパースして作る
- PDF化する
PDF化には、WeasyPrintを採用しました。WeasyPrintはPythonライブラリとして提供されており、HTMLとCSSをPDFに変換できます。特に、CSSによる細かなレイアウト制御が可能で、ページ番号やヘッダー・フッターの設定も容易です。
表紙はMarkdownの力だけで中々綺麗なものができないため、別途で用意します。 そして、HTMLからh1,やh2の見出しのタグを取得し、それを使って目次の要素を追加します。 最後PDF化した際に、目次のページ番号・印刷時にページ番号を表示するCSSを適用します。
表紙と目次とページ番号も揃ったPDFマニュアルができました！
AIでのマニュアル自動生成を実現するポイント
ここまでの仕組みにより、AIを活用したマニュアル自動生成を実現できます。
テキストベースなのでAIが修正しやすい
Markdownはテキスト形式で記述されており、WordやNotionのようなバイナリ形式ではありません。そのため、AIが直接ファイルを開いて編集・修正することが可能です。AIが生成した文章をそのままマニュアルに反映できるため、手動での修正工数が大幅に削減されます。
構造化されているからプロンプトが明確
ディレクトリ構造やファイル名が体系的に整理されているため、AIへのプロンプトが非常に明確になります。例えば「以下のAPIドキュメントを参考に、01_setup/03_api_guide.mdを作成してください」といった指示を出すだけで、AIが正確にマニュアルを生成できます。この構造化により、AI活用の精度が飛躍的に向上します。
画像管理がシンプルで自動化しやすい
画像はassetsフォルダで一元管理され、Markdownでは
{ width=100% }
といった統一的な記法で参照されます。このシンプルで規則的な画像管理体系により、AIが正確に画像パスを生成でき、画像の挿入位置やサイズ指定も自動化できるようになります。
バージョン管理による品質保証
Gitでの管理により、AIが生成した内容の変更履歴を完全に追跡できます。どのAIが、いつ、どの部分を修正したのかを明確に記録し、問題が発生した場合でも、以前のバージョンへ簡単に復元できます。さらに、このようにAIの出力を詳細に記録することによって、継続的な品質向上も可能になります。
複数出力形式への自動変換
1つのMarkdownソースから、Web版マニュアル（Mkdocs）とPDF版マニュアル（weasyprint）が自動生成されます。将来的に他の形式への拡張も容易です。この自動化により、AIが生成した修正が一度で全ての形式に反映されるため、マニュアルの一貫性を保ちながら、複数の配布形式に対応できるようになります。
最後に
今回、Markdownを活用したWebマニュアルとPDFマニュアルの両立できる作成手法を紹介しました。特に病院向けシステムという特性上、オフライン環境でも利用可能なPDFマニュアルの重要性は高いです。
このように、当社では技術的な課題に対して、既存の方法にとらわれず、より良い解決策を模索し続けています。新卒社員にも、自由な発想で問題解決にチャレンジする機会が多くあります。
DX推進に興味のある方、ぜひ当社の採用情報をチェックしてみてください。 www.optim.co.jp
