Vivliostyleとは

Vivliostyleとは、Web技術を用いた組版ツールです。基本的には独自のViewerをPlaywrightで表示させ、それを元にPDFやEPUBを生成する仕組みのようです。

今まではAsciidoctorでドキュメントを作成していましたが、レイアウトで融通が利かない場面が多く、もっと簡単かつビジュアルもよい文書作成ツールが無いかなと探していたところ、Vivliostyleに行きつきました。結論から先に書くと、どっちもどっちです。あちらを立てればこちらが立たずと言うところ。ただし、Vivliostyleの方に将来性を感じます。今回はVivliostyleを用いた技術系ドキュメントの作成例があまり無かったので、作成してみました。

生成ドキュメント

ソースはこちら
https://github.com/MichitoIchimaru/vivliostyle-techdoc
生成されるドキュメントは以下のようなレイアウトです。

表紙	改版履歴
目次	段組み1
段組み2	Mermaid

解説

ソースの解説はGithubのpdfに詳しく書いているので、こちらを見てください。
https://github.com/MichitoIchimaru/vivliostyle-techdoc/blob/main/dist/TechDoc.pdf

こだわりポイントとしては「目次」です。Markdownの番号付きリストをそのまま使うと、分かりにくい目次となってしまいますが、そこを次のように改善しています。


1. 章1
    1. 節1-1
    2. 節1-2
2. 章2
    1. 節2-1
    2. 節2-2

→


1. 章1
    1.1. 節1-1
    1.2. 節1-2
2. 章2
    2.1. 節2-1
    2.2. 節2-2

これがこだわりかよと思われるかもしれませんが、これが思いのほか難しく、番号だけなら簡単なのですが、後ろのページ番号を揃えて表示するのがかなり難しかったです。詳しくはPDFを見てもらえると分かりますが、これはレンダリングのバグでたまたまうまく表示されているんじゃないかと思えます...
逆にこだわれなかったポイントとしては、Mermaidです。Vivliostyleのpreview機能では問題なく表示されるのですが、buildしてPDFを生成するとMermaidの図が表示されません。もしくは潰れて表示されます。Vivliostyleのソースを色々といじって試してみましたが、だめでした。Mermaidの図形を含めて印刷する場合はpreviewの印刷機能から実施するしかありません（GithubのUsage参照）もしくは、MermaidのテキストをMarkdown中に埋め込むのではなく、VSCodeなどで一旦画像化したものを埋め込むようにするしかないです。PDF生成までをパイプラインで流す場合はそうするしかなさそうです。
以下はVivliostyleに対して色々やった内容です。

待ち時間を入れてみる
Playwrightが描画しきる前にPDF化が走っているのではないかと思い、ページ表示後に数秒のwaitを入れてみましたがだめでした
svgを画像に変換してみる
svgがよくないのかと、mermaidで生成されるsvgをbase64の画像に変換し、svgタグでなくimgタグを挿入するようにしてみましたがだめでした
Playwrightのヘッドレスモードをオフにしてみる
Playwrightのヘッドレスモードとの相性が悪いのかと思い、ヘッドレスモードをオフにしてみましたがだめでした。browser.close()している箇所をコメントアウトし、PDF化の際にタグがどうなっているかを開発者モードで見てみましたが、正常に挿入されていました。Elementにマウスオーバーすると、ちゃんと描画領域が色反転する（けどなぜか表示されていない）ので、何かが悪さをしている様子。けどその何かが分からず断念（助けて中の人）

MS Officeではダメなのか？

決してMS Office製品が嫌いとかそういうわけではないんですが、MS Officeで設計書やマニュアルを作成すると、必ずこういう場面に出くわします。

いつ誰がどう編集したのか分からない
同一文書内でフォントや文字の大きさが統一されていない
どれが最新版か分からない
複数人で執筆しにくい

これらに関しては反論もあると思います。履歴機能を使えばよいとか、SPO（SharePointOnline）上でメンテすればいいとか、そもそも文化の問題であってMS Officeの問題ではないとか。MS Officeはもちろん強力なツールであり、日本企業であれば、まず間違いなく誰でも使えるであろうというメリットがあります。そのため、納品対象のお客様が「必ずファイルを開ける」という理由で設計書やマニュアルをMS Office製品で作っているところも多いと思います。Excelの表機能、グラフ機能は超便利です。
しかし、テキストを編集するだけでビジュアル的にも見やすいドキュメントが生成できるのであれば、絶対にそちらの方が良いです。gitで管理することで、いつ誰がどう変更したか、細かいところまで一目瞭然ですし、gitの比較機能を使えばレビューもめちゃくちゃ楽です。何より、パイプラインに乗せることで、pushやmergeした際に自動でPDFを生成し、必要があればSlackやTeamsに通知したりすることが可能です。最新版がどれか分からないなんて問題はまず発生しません。
私も幾度となく脱Officeを掲げているのですが、その度に、融通が利きすぎるMS Office製品とgit使えないおじさん達に阻まれます。なので、Vivliostyleがもうちょっと扱いやすくなって推しまくれる状態になれば、どんどん推奨していきたいところ。

今の日本のSIerの開発スタイルは無駄や技術的負債が多い

海外を知っているわけじゃありませんが...　そしてこれはあくまで個人の感想です。

結局実際のシステムと乖離やメンテ漏れが発生する
WFにおいて（アジャイルだから違うというわけではありませんが）、設計してからコードを書くということは、日本語で文書化して、その文書から英語に翻訳するようなものです。つまり、言語が違うというだけで結局同じ作業を2回実施していることとほぼ同義です。それを繰り返しメンテしていたら、いつか絶対に乖離が出ます。私は、設計書は画面設計、画面項目定義、テーブル（スキーマ）設計、API設計だけで良いと思っており、詳細なシステム設計やプログラムの内部の挙動を事細かく定義するような設計書は不要だと思っています。そんな時間があったら実際のDBでスキーマ定義してSQLの実行計画を解析しながら設計したり、コード組んでみて性能検証したりする方がよっぽど有意義です。次工程を実施する人が別の人で、細かく書かないと伝わらないという場面は確かにあります。細かい部分は画面項目定義やOpenAPIやWikiに文字で書けばよく、普通の技術者であればそれで事足ります。また、実際のDBのスキーマからMarkdownを生成してくれるtblsやOpenAPIからMarkdownを生成してくれるツールを使うことで、Vivliostyleなどと組み合わせて簡単にドキュメント起こしすることも可能です。
https://github.com/k1LoW/tbls
https://github.com/OpenAPITools/openapi-generator
前提知識ゼロの人が読んでも決して理解できない書き方となっている
前述のように、後工程を実施する人が別の人であることを前提に、細かく設計書に記載されます。しかし、設計書なんてプロジェクトが違えば書き方も内容の粒度も異なります。ベテランのエンジニアでも違うプロジェクトの設計書となると理解するのに時間がかかります。ですが、実際のDBスキーマやOpenAPIは万国共通です。どんなエンジニアだろうが理解可能であり、認識が異なるということはまずありません。そしてメンテナンスが容易です。そういった容易に設計できるツールからドキュメントを起こした方がコストも品質もだんぜん良いはずです。ExcelやWordで書かれた、慣れ親しんだ書き方の設計書しかレビューできないという人が残念ながら居ると思いますが、そういう人にレビューしてもらったとしても、絶対に品質は上がりません。その人が幹部社員であれば、ピープルマネジメントに専念してもらい、（自称）技術者であれば早々に現場から退場してもらいたいところです。

参考

Vivliostyle Viewer で CSS 組版ちょっと入門
Vivliostyle-CLIでmermaid.jsを使用する