デジタル庁も囚われている日本のIT業界の悪癖：Excelによる仕様書・設計書の作成

表計算ソフトのExcelで作成した仕様書・設計書は、前世紀から日本のIT業界の悪癖として知られている。

Excelは構造化文書を書くための機能がないため、目次や索引などを自動作成できない。ソフトウェア開発のための図表描画機能がないため、作図も手間暇時間のかかる職人芸になってしまう。セルの結合と装飾、オートシェイプをつなぎ合わせてソレらしいものを描くことになるため、変更時の修正量が多くなるし、ちょっとしたことでレイアウトが崩れる。用紙サイズの設定も狂う事が多い。2010年頃からはバージョン監理システムでトラッキングしづいこと、最近は生成AIの読み込ますには無駄が大きいとことも、欠点として指摘されている。

この悪癖は、大手から中小零細まで広く行き渡っている。デジタル庁も.xlsxの仕様書を出している。そのうちの一つ「地方公共団体情報システム 共通機能標準仕様書 OAuth2.0アクセストークン発行API仕様 第1.3版」を見てみよう。表計算の機能は使っていない。目次はない。セルを連結して文書のスペースをつくっている。表にしているが、項目説明、備考、記述例などの文字数が多い（それぞれ節を分けるべき）。オートシェープでシーケンス図が描いてある。中央に追加があったら、下半分の位置を動かした上で、配線をやり直さないといけない。レスポンス_API仕様のJSONの説明が…ネ申EXCEL(´･ω･`)ｼｮﾎﾞｰﾝ

他の仕様書も幾つか見た限りでは、表計算で書くべき理由は無さそうであった。

1. MarkdownとMermaid.js/PlantUML/Graphvizのススメ

Excelによる仕様書作成から脱却すべきだ。Markdown形式のテキストに、ソフトウェア開発のための図表（e.g. ERD, UML, State Diagram/画面遷移）をサポートするMermaid.jsのコードを埋め込むのが最近の流行りで、構造化文書の作成と効率的な作図が可能になる。テキストによる図表作成が苦手な人にはdrawDBというエディターもあるし、JavaScriptに過度に依存したくない場合は、PlantUMLやGraphvizといったツールもある。

Markdown記法が難しいといっているソフトウェア・エンジニアがいて面食らうのだが、そんなことはない。使用頻度が高いのは、見出し、箇条書き、表、画像埋め込み、エスケープぐらいであるし、ハイパーリンク、強調、下線、引用を足しても大したことにはならい。✓のような数値参照入力の仕方をしっておけば、絵文字を使いこなすこともできる。入力が正しいか確認できるエディターは欲しいところではあるが、人気のエディターVSCodeは標準サポートで、2026年5月20日からはMermaid.jsのプレビューにも標準対応した。

Markdown記法はPandoc（かそれを利用したQuarto/Rmarkdown）でHTML、PDF、DOCXに変換できるので、非技術者に配布にも対応しやすい。

2. コードによるシーケンス図作成例

作図の効率性は大幅に高まる。デジタル庁の.xlsxファイルのシーケンス図を、PlantUMLで書き直してみた。

.xlsxファイルのシーケンス図は以下で、

PlantUMLで描きな直したモノが以下。

見た目は変わらないが、記述は以下のように全てテキストだ。

@startuml

actor システム利用者 as USER
participant "要求元システム\n（クライアント）" as CLIENT
participant "認証認可サーバー" as A_SERVER
participant "要求先システム\n（リソースサーバー）" as R_SERVER

group ①アクセストークンの発行
USER -> CLIENT : ①-1 システムにアクセス
CLIENT -> A_SERVER : ①-2 アクセストークンを取得
note right : [oauth/v1/token_R01]\nOAuth2.0アクセストークン発行要求電文\n（リクエスト_API仕様を参照）
A_SERVER -> CLIENT : ①-3 アクセストークンを返却
note right : [oauth/v1/token_S01]\nOAuth2.0アクセストークン発行応答電文\n（レスポンス_API仕様を参照）
end

group #999999 ②アクセストークンの情報取得
CLIENT -> R_SERVER : ②-1 リソースを要求
R_SERVER -> A_SERVER : ②-2 アクセストークン情報を取得
A_SERVER -> R_SERVER : ②−3 アクセストークン情報を返却
R_SERVER -> R_SERVER : ②-4 アクセストークン情報を認証
R_SERVER -> CLIENT : ②-5 リソースを返却
CLIENT -> USER : ②-6 システムの処理結果を返却
end

group #999999 ③アクセストークンの無効化
USER -> CLIENT : ③-1 システムにアクセス
CLIENT -> A_SERVER : ③-2 アクセストークンの無効化を要求
A_SERVER -> CLIENT : ③-3 アクセストークンの無効化の結果を返却
end

@enduml

命令を検索しながら（か生成AIに相談しながら）書く必要はあるが、プログラミング言語ほどの複雑さはない。コピペで済む。処理を増やしたり減らしたりしても、レイアウトのし直しに苦労することはない。

オープンソース製品を紹介したが、Microsoft社のVisioのようなプロプライエタリ製品もある。ERDやUMLようなフォーマルなものではない大雑把な画面設計をWYSIWYGで描きたい場合は、LibreOfficeのDrawで作画してSVG出力し、Markdownで読み込む方法もある。ネットワーク機器のシェープとAWSアイコンを入れておくと、ネットワーク構成の作図に便利だ。描き心地はオートシェイプと同様ではあるが、用紙サイズはずれない。

3. ここはテックギーク感を発揮すべき

前世紀は普及している図形描画アプリケーションが無かったので、プリインストールのMS-Office製品で何とかしたかったのは分からなくもない。21世紀に入って、Microsoft社が買収したVisioなどの作図ツールや、その他の設計支援ツールに手が出なかったのが、ソフトウェア購入費を抑制しようと言うケチ臭さからくるのも分からなくもない。しかし、成熟したオープンソースの作図ツールが2020年代に、表計算ソフトで何とかしようと言うのは怠惰を通りこして狂気だ。

DXの徹底的推進云々と言っているデジタル庁の皆さんには、この辺も何とかして頂きたい。Decap CMSで云々と語る前に、こっちを何とかすべきだったと言うか。エンドユーザーには直接関係ないが、ソフトウェア・エンジニアのマンパワーが無駄なところにとられて、推進力が落ちる。