はじめに

最近、設計書をAsciiDocで書いてGitで管理することに挑戦しよう！という現場に行き会いました。
Gitで管理できないバイナリファイルつまり（つまりOffice系）はもう嫌だ！という動機で、AsciiDoc万歳の流れに乗った形なのですが、これは、このまま進んでいいのか？と思う点があったので、思い出しながら記事にするものです。

AsciiDocで検索すると「Gitで管理できて万歳！」みたいな情報ばっかり見たので、アンチテーゼとして公開したい気持ちもあります。

AsciiDocの利点はわかっているのだけど

「軽い」とか「複数人で同時に編集できる」とか「簡単にきれいな文書ができる」とか。
いろいろ見かけました。「壊れない」とかね。
とはいえ、やはり1番の理由は「Gitで管理できる」これなのかなぁと思います。

Excelの問題をAsciiDocは解決する！なのかなと。

AsciiDocには難点もいろいろ

列挙してみます。

表現はレンダリングエンジンに依存する
マークダウンと違って記法に方言がないとはいえ、編集エディタ(VSCodeとか)と、Gitホスティングアプリ(Gitlabとか)と、PDF化した状態で、表現がぜんぜん違う。方言はないはずですが、文字色を変えても、エディタでは見えて、PDFでは見えない、みたいな問題もあったり。(直し方はあるんでしょうけど・・・)
ファイル構成が肥大化しがち(画像やcsvなど差し込みたいので)
お客さまウケがよくない、むしろ嫌がられる
表が書きにくい
フロー(mermaid)やUMLも、便利だけど、いざ編集したいとなったら読解が大変
吹き出しでコメントをつけたり、ちょっとした(Excelなら簡単にできた)ことができない

要するに、ExcelでできることがAsciiDocだとできない！！！のです。

このまま進んでいいのだろうか？

で、タイトルの疑問に至ります。
上位互換というか、Excelでできることを全部できたうえで、さらにGitでも管理できて軽くて、だったら、問題ないと思うんです。
でも、Officeの設計書とAsciiDoc設計書は機能をトレードオフしている。
そうなると、あとはメリデメを比較してどっちをとる？という話になると思うんですね。

それは現場とステークホルダーの判断になるのでしょうけど、
少なくとも私個人はOfficeを推したいです。

AsciiDocで作る設計書の世界って？

「Gitで管理できて万歳！」みたいな意見をちらほら見るんです。
もう設計書はこれで書きたい！みたいな。
でも、じゃあ、実際ほんとにやってるプロジェクトってどれだけあるんだろう？
と、軽く調べてみたところ、すごい大御所的なやつが見つかりました。
設計書ではないのですが、ProGit v2がAsciiDocでした。
ソースコードもこちらで公開されています。

そうです。ソースコードです。これはもうソースコードだと思うんです。
ソースコードの設計書をソースコードで書く的な世界です。

「AsciiDocで設計書をつくる」を選択するなら、設計書の概念を根本から捉えなおすくらいの気構えがないといけないような気がします。

なんだか、全体にちょっとボヤキっぽくてすみません。
以上でした。