我々はいつまでExcel方眼紙のメンテで疲弊し続けるのか
Excel方眼紙は悪である。
唐突だが、まずこの命題に同意いただけないならこの記事は君に必要ない。
そっとこのページを閉じ、他のイケてる投稿を読むなり、Excel方眼紙のセルのズレを直すなり、100,000行目にポツンと書き込まれたテキストを消すなり、分数を入力したら日付として扱われてげんなりするなり、おもむろに置かれた図形を動かしてその下に計算用のセルが隠れているのを見つけてニヤリとしたりすればいい。
この記事はそういうことが不毛だと日々感じている多くの技術者に向けている。
ちゃんと伝えたぞ、以降は冒頭の命題に同意してくれた人にフォーカスして話をすすめる。
「いやでもExcel方眼紙にもこういうメリットが」とかいう泣き言は受け付けない。
なお本来の表計算ソフトとしてのExcelの価値は現今最高であることは付記しておこう。
Excel方眼紙がいかに邪悪であるか
本論の趣旨は現実的な代替手法の提案であり、すでに問題は認識している人に向けての記事であるため、
「なぜExcel方眼紙が悪であるか」についていまさら多くの項と時間を割きたくはないのだが、前提として改めてなぜExcel方眼紙をなくさなければならないのか簡単に整理しよう。
検索性
方眼紙でできた大量の資料から特定のキーワードを抜き出すのは熟練の業が必要となる。
そのためのツールはいくらでもあり、なんなら雑な機能でいいなら自分で書くのもそれほど難しくないから「不可能」というと嘘になるが、どのような方法でも即座に結果が返って来ることはない。
検索を書ける度に毎回コーヒーを淹れるだけの時間的余裕と丈夫な胃をお持ちであるなら問題にはならない。
差分比較可能性
xlsはもはや引き合いに出すのはフェアではなかろうから無視しよう。
xlsxの実体はzipでまとめられたxmlだ。資料の修正前後のファイルのどこが修正されたかを専用の機能を使わずに歴史として残したければ、編集したxlsxを展開してxmlをgitに上げれば差分がテキストで残せるということだ。xmlなら比較できる。その差分を人が見て分かりよいかは知らない。
おやなんてことだ、差分が比較できないことを説明しようとしたら出来てしまった。
まぁそんな管理がどうしてもしたければ私に直接影響がない限り止めはしない。頑張ってくれ。
ストレージ圧迫
よもやこれを読んでいて所属組織がgitのようなバージョン管理システムを導入していない者は無いだろう。
xlsxだろうがpngだろうがgitのリポジトリに突っ込んでおけばバージョン管理はできる。
そういう方法を取ってる組織もあることだろう。
まぁ、oldのディレクトリに古いファイルを押し込めて後生大事に置いておく方法よりは幾分かましだ。
ここでいう「まし」っていうのは暗闇を照らすのにマッチよりはライターのほうがまし、程度の「まし」よ。
懐中電灯をつかったほうがいいに決まってるじゃない。
gitのデータ保存の仕組みについて講釈を垂れるつもりはない。結論だけ言おう。
xlsxを含めバイナリファイルはコミットごとにほぼ修正したファイルサイズ分のストレージを食う。
それが例え1文字の修正だろうが、1MBのxlsxを修正の都度コミットすることを100回繰り返せばリポジトリのサイズは100MBになるってことだ。
組織が大きければまたたく間にリポジトリは肥大化する。
気づいたときにはまともにcloneすることも出来なくなるだろう。
depth 1 でcloneすれば...
Git LFSで...
そういう細かいことは言いっこなしだ。中央リポジトリが肥大化すること自体が回避できるわけでもない。
git-annexで...
実際gitでバイナリファイルを使いつつリポジトリの肥大化を防ごうという試みは消えたプロジェクトも数えれば相当ある。
それらが普及していないことがそのソリューションが適切でないことのなによりの証左だろう。
画像や音声、動画を主に扱う中での利用は検討に値するが、本質的にはテキストで記述出来る資料であるのに、Excel方眼紙を使って書かれているせいでうまく管理出来ない資料をなんとかするために追加の仕組みを入れるのは典型的なアンチパターンだ。
最低の肉でもこのソースでなんとか食えるって？味は知らんがその肉はどうしても食べないといけないのか？`
いうまでもなくテキストファイルであればその限りではない。そうだ、これもxmlに展開して管理すれば解決ってことだ。
そんな管理がどうしてもしたければ私に直接影響がない限り止めはしない。頑張ってくれ。
挙げ始めると問題はいくらでも出てくるがこの辺にしておこう。もっと欲しければネットの海にいくらでも浮かんでるから、そっちに当たってくれ。
そんなに邪悪なものがなぜ採用されるのか
そんなに悪いものならそもそも採用されないはずではないか、しかしExcel方眼紙は世界に氾濫している。
こんなにも邪悪なるExcel方眼紙がなぜ跋扈するのか。
実は自分だけが知らない魔法の管理方法が存在していて、みんなはそれで難なく業務をこなしてるのか？
そんな不安すら感じてしまいそうだ。
これも理由は一つではないが、
メンテを考えなければ直感的に作図でき、かつ普及しているツールとしては優秀と言わざるを得ない。
このメンテを考えなければが一番問題なのだが。
大抵の資料は最初に書かれるのに費やされる時間よりその後メンテし続ける時間のほうが大きい。
このイニシャルとランニングのコストへの無自覚こそ悪の蔓延を招いている。
注意一秒怪我一生というやつだ。
もしターミネーターを過去に送り込めるなら、ジョン・コナーみたいな小物よりExcelに図形を追加できるよう提案した奴をターゲットにするべきだ。
そして一度Excel方眼紙を採用したが最後、そのプロジェクトで資料のフォーマットを変えるのは至難の業だ。
変えるためには根拠とその説明資料と関係者の協力が必要となり、ときにそのコストは無限大となる。
一度決めた習慣・ルールを容易に変えることができるならあんなシステムはとっくになくなってるはずだ。
あんなシステムのところは各自好きに読み替えてくれ。
毎週落ちてたうちの業務システム、最近調子いいわね。
なんか、インデックスがどうとか言ってたわ。本当困る
え？
オレ、あの復旧のためだけに採用されたんだよね。
結局何で資料を書けば良いのか
さて前置きが長くなった。
文句ばかりで代替案がだせない技術者ほど厄介な存在はない。
まどろっこしいことは言わない、結論から言おう。AsciiDocだ。Markdownも悪くはないが表現力に難がある、かゆいところに手が届かない。
QiitaもAsciiDocをサポートしてくれ。
素のAsciiDocでも私の知る限り世の中のExcel方眼紙の50%は代替可能だ。
50%じゃ低すぎると言われるだろう。あとでちゃんと回収するから少し我慢してくれ。
AsciiDocを推す理由もまた複数あるが、今回の文脈においてMarkdownとの比較で重要な点を２つだけ挙げよう。
一番かゆいところだ。
結合セル
なにあろうMarkdownのテーブルではサポートしていないテーブルの結合セルである。
AsciiDocではこのように書くことで
[%header]
|===
|大項目|中項目|小項目
.3+|1 .2+|A |イ
|ロ
|B |ハ
|===
結合セルが表現できる。
| 大項目 | 中項目 | 小項目 |
|---|---|---|
| One | A | イ |
| ロ | ||
| B | ハ |
なおこのテーブルはHTMLを直書きしている。実際のAsciiDocが生成するものとは表示の解釈が少々違うのはご容赦願いたい。
なら結局MarkdownでもHTMLを書けばいいじゃないかとか言うのなら頼むから黙って一生アセンブリだけ書いててくれ。
設計資料などでセルの結合が出来ると出来ないとではデータ構造の表現力がまるで違ってくる。
むしろなぜMarkdownがサポートしていないのか理解に苦しむ。
ニーズは間違いなくあるはずだが誰かその議論について知っていれば教えてほしい。
少し苦言を呈するなら、結合などのセル属性の記法がやや魔術じみている。
例で言うと.3+の部分がrowspan=3に相当するのだが、もうちょっとヒューマンフレンドリーに出来たろうに。
(r3とかでよくない？)
その他Markdownとの比較についてはQiitaのこの記事がよくまとまっている。
AsciiDoc自体の機能はこちらが良い。
そして公式ドキュメントを通読するのが最終的には最も近道であることは言うまでもない。
当然のことだが公式ドキュメント自体AsciiDocで書かれている。
なんで我社のAIシステムは売れないんだ！？売れるって言ってたよな！？誰だ、その判断したやつは！？
我社のAIでございます。
include
もう一つ、重要な機能がincludeだ。
AsciiDocは別で書かれたAsciiDocを参照して埋め込む事ができる。
もっといえばAsciiDocに限らずテキストファイルなら何でも読み込めるのだが、ここではAsciiDocに絞って話そう。
World!
に対して
Hello
include::world.adoc[]
が同一ディレクトリにあるなら、hello.adocをAsciiDocとして評価すると
Hello
World!
となるわけだ。
これがシンプルながら強力な機能であることは論を俟たない。
[]内にオプションが書け、lines=2..5といったように行の指定が出来るので別の資料に書いた内容を一部だけ抜粋して引用したいときに二重管理せずにすむ。
(行がずれる問題は如何ともし難いが)
この機能はカスケードが出来るから、world.adocが更に別のファイルを読み込める。
少々脱線するが、では循環参照したらどうなるだろうか。
world.adocを以下に書き換える
World!
include::hello.adoc[]
エラーとなるかと思いきや、後で紹介する私の手元の環境(vscode)では64回のincludeが処理された後(つまり32回Hello Worldが表示され、33回目のHelloの後)、単に
include::world.adoc[]
がそのまま表示されたままとなった。
数は処理系や設定によるのだろうが、循環参照であるかに関わらずincludeのネストの上限が決められているようだ。
ちなみに試すのであれば２つのファイルを用意するまでもなく、単にそのファイルからそのファイル自体をincludeすればよい。
もう少し脱線を許して欲しい。
おそらくこのincludeの動作がMarkdownに比べてAsciiDocをサポートするサービスがいまいち増えない理由だろう。
Markdownは単一のファイルで完結するため、一つのファイルを展開するのに必要なリソースは固定的だ。
サーバ側で展開せずすべてブラウザに任せる事もできる。
しかしAsciiDocはこのincludeの機能によってサーバで結合処理しなければならない。
(Ajaxでなんとか出来ないこともないだろうが)
当のファイルに更新がなければキャッシュを使う、という判断も出来ない。
別ファイルを参照させるというのはセキュリティ上考慮しなければいけないことも出てくる。
../../とディレクトリをたどってシステムの管理ファイルや別ユーザのファイルを参照するなんて手は一昔前のよくあるハックだ。
とまぁ普及率を考えればあまり実装したくないだろうなという想像がつく。
なぁそういうことなんだろう？Qiitaさんよう
しかし、その上でGitHubがサポートしているという事実は改めて伝えて置きたいところだ。
なお、GitHubではincludeは単にinclude先の資料へのリンクとなる。
まぁこのあたりが落とし所だろう。
作図問題
AsciiDocが良い資料作成ツールであることはわかったが、これだけではExcel方眼紙を置き換えられない。
なにしろ我々の前にはまだ50%の方眼紙が立ちはだかっている。
この50%はなにかというと要するに「図(ダイアグラム)」だ。
システム概要図に状態遷移図、ER図にシーケンス図。
この世界には図示しなければならない資料が山ほどある。
百聞は一見にしかずとはよく言ったもので、文章だけで長々と説明するより1枚の絵のほうが100倍伝わることは珍しくない。
ならば当然作図が自在にできるかどうかがその資料作成ツールが使用に耐えるかどうかの分水嶺である。
残念ながら素のAsciiDocではきれいな図を表現することは出来ない。
罫線を駆使してアスキーアートを書くのが関の山だ。
しかし、テキストを元に図を生成するという発想で作られたツールがいくつかある。
代表的なところではPlantUML、Ditaa、mermaidなどだ。
あれもこれもという話をすると収集がつかないので個人的によく使ってきたmermaidを前提に話を進めよう。
主観だが、mermaidだけでも世の中のExcel方眼紙で作られた図の95%は置き換える事ができると思っている。
mermaidで書ける図は結構制限があるものの、実際のところ本当に資料に必要な図というのはその程度で十分表現出来るものだ。
もちろん営業がユーザを騙すの目を引くために使う華々しい図は望むべくもない。そういうのはパワポ職人に任せればいい。
mermaidで書ける図は実質剛健でわかりやすく、システムの資料に使うべくして使えるものである。
話が飛ぶようだがテスト駆動開発が知名度を得てからというものこういうことが言われるようになった。
Q. テストしにくいコードをどうすればいいか。
A. テストしにくいコードというのはそもそも構造が良くない。テストしやすいコードがより良いコード。つまり書き換えるべき。
雑な問答になってるのはお目溢しいただくとして、
これをそのまま作図に敷衍してこう言おう。
Q. mermaidで表現し難い図をどうすればいいか。
A. mermaidで表現し難い図というのはそもそも構造が良くない。mermaidで書ける図こそより良い図。つまり書き換えるべき。
まぁどうしようもない図は存在する。たいていその図示しようとしているシステム自体がどうしようもないのだが。
最後の手段として画像化して貼り付けるという方法は常に残されている。AsciiDocを諦めてはいけない。
vscodeでAsciiDoc
さて、AsciiDocを拡張することで前述の作図ツールを使って生成した図を埋め込む事ができる。
CLIでgemをつかってasciidoctorとasciidoctor-diagramをいれてadocを渡して、なんてのが基本ではあるんだが、
今どきそんなのは流行らない。
とにかくadocの中に図の元となるコードを書いてその場でサクッとプレビューされて欲しいんだろ？
さぁみんな大好きvscodeの出番だ。
長々と語ってきたがはっきり言ってこの記事の価値はここからの十数行程度だけかもしれない。
vscodeでこいつを入れる
https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode
説明に従ってインストールする。
これだけでAsciiDocを書いてそのプレビューは出来るようになり、PDFも出せる。
だが、デフォルトでは作図ツールは有効になっていない。
有効にするにはsetting.jsonに以下を設定する。workspaceで設定するかuserで設定するかは任せる。
"asciidoc.use_kroki": true
krokiとはなんぞやと思うところだろうがまずは思考停止して設定してみる。
設定したら試しに適当な.adocファイルを作ってプレビューを横に出しながらこんな内容をいれてみるといい。
[mermaid]
----
graph LR
Me-->|Love|You
----
プレビューにはこんな具合に表示されるはずだ。
Loveは一方通行のようだがそれは仕様通りである。
設定一つでmermaidに限らず多くの作図ツールが使えるようになる。
魔法のような機能に喜び勇んで社内のシステム図を早速こいつで作ってみようと思う前にちょっと待って欲しい。
実はこいつは結構な問題を抱えている。
エクステンションの説明にはこう書かれている。
Note that this extension will send graph information to https://kroki.io.
英語が苦手でもこの程度なら何のことはないだろう。
この作図機能は https://kroki.io なるWebAPIを利用していて、手元で書いた作図のソースをこのサービスに送信し、画像データを受け取ってAsciiDocに埋め込んでいるってことだ。
こいつは説明書を読まずにとりあえず使って見るタイプの人間にはなかなかの落とし穴だ。
一方通行の愛はこのサービスに丸見えになっていた。はずい。
これはどうしたって一度送信可否を尋ねるダイアログを出すべきだろう。
会社組織のセキュリティというのは漏れた情報が実際に損害を出すかどうかではなく、
損害を出すかどうかを判断する必要もない状態とすることが求められる。
要するになにも外に出すなということだ。
何の気なしに使っていたツールで社内システムの構成情報が外部サーバに送信されていたとなれば大騒ぎになる会社も少なくないだろう。
(プロキシを通してまともに動くのかは知らないが)
逆に言えば送っても差し支えない情報であればここに書かれている様々な作図ツールを試す事のできる機能として非常に優秀だ。
当然社外に出せないデータもあるだろうという配慮はあり、このkroki.ioはdocker-composeで立ち上がるコンテナイメージを提供してくれている。
社内でこのコンテナを立ち上げてリクエストの送り先を切り替えることでイントラ内で完結出来るってことだ。
ここまで読んだ君たちなら、Excel方眼紙を撲滅できると思えばその程度の労はきっと厭わないと信じている。
そんな大仰なものは求めてない件
いやまてまて、PlantUMLはjavaのサービスとして立ち上げる必要があるなど、少々厄介なのだが、私としてはmermaidだけで十分なのだ。
mermaidはjsで書かれている、つまりクライアントだけで動作する。にもかかわらずたったこれだけためにコンテナを立ち上げるなどしたくないのだ。
そもそもExcel方眼紙をなくしたいというのに、Dockerを、などと言ってる時点で勝ち目はない。
もっとこう、自由で、なんというか、救われてないとだめなんだ。
Markdown + mermaid であればローカルだけで完結するエクステンションは存在している。
https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid
これをAsciiDocでやりたいだけなのだ。
長くなってきたのでこれをどうにかするための話は気が向いたら別で続けたいと思う。
ネーミングセンス
最後にこれだけ言わせてほしい。
AsciiDoc。アスキードック。
言及している記事は他に見当たらなかったが、ひどいネーミングだと思う。
体を表した良い名前だという人もあろうが、イケてる技術感がまるで無い。90年代の技術っぽい。
流行らない理由は名前によるところが大きいと結構本気で思ってる。