はじめに
システム開発の現場では、長らくMicrosoft ExcelやPowerPointがドキュメンテーションツールとして広く利用されてきました。これらは視覚的に分かりやすい資料を作成できる一方で、バージョン管理の困難さ、テキストベースでの再利用性の低さ、共同編集時のコンフリクトといった課題も抱えています。特に近年注目される生成AIの活用においては、バイナリ形式が中心となるこれらのツールは、AIによる内容の解析や生成、編集といった処理との親和性が低いという側面があります。
このような背景から、テキストベースの軽量な記述言語であるマークダウン、YAML、JSONが、ExcelやPowerPointの代替となるドキュメンテーション手段として注目されていますし、私個人としても注目しています。これらのフォーマットは、プレーンテキストで記述されるため、Gitなどのバージョン管理システムとの相性が良く、差分管理が容易です。また、テキストエディタで手軽に編集でき、ツール連携も豊富であるため、開発プロセスへの統合がしやすいという利点があります。さらに、テキストベースであることは、生成AIが内容を理解し、ドキュメントの自動生成や要約、質疑応答などを支援する上で大きなアドバンテージとなります。
本稿では、システム開発ドキュメンテーション（要件定義、設計、実装、運用全般）において、マークダウン、YAML、JSONをExcelやPowerPointの代替として利用する可能性を探るため、それぞれの特徴を網羅的な観点から比較検討します。比較にあたっては、記述のしやすさ、可読性、表現力、構造化データの扱い、ツール連携、学習コスト、バージョン管理のしやすさ、生成AIとの親和性、ドキュメントの種類との適合性、そしてExcel/PowerPointとの比較といった多角的な視点から分析を行います。
各フォーマットの概要
マークダウン (Markdown)
マークダウンは、プレーンテキストに簡単な記号（例: #, *, -）を付与することで、構造化された文書（見出し、リスト、強調など）を作成するための軽量マークアップ言語です。元々はHTMLへの変換を容易にする目的で開発されましたが、そのシンプルさと可読性の高さから、READMEファイル、ブログ記事、技術ドキュメント、議事録など、幅広い用途で利用されています。人間が読み書きしやすいことを重視しており、特別なエディタがなくても内容を理解しやすいのが特徴です。
YAML (YAML Ain't Markup Language)
YAMLは、人間にとって読みやすいデータシリアライゼーション言語です。インデント（字下げ）によってデータの階層構造を表現するのが大きな特徴で、設定ファイル（例: Docker Compose, Kubernetesマニフェスト, CI/CDパイプライン定義）や、異なるプログラム間でのデータ交換によく用いられます。括弧やカンマの使用を極力排し、自然言語に近い感覚で記述できるため、複雑な設定や構造化されたデータを直感的に表現するのに適しています。コメントも記述可能です。
JSON (JavaScript Object Notation)
JSONは、JavaScriptのオブジェクトリテラル記法をベースにした軽量なデータ交換フォーマットです。キーと値のペア（オブジェクト）と、順序付けられた値のリスト（配列）を組み合わせてデータを表現します。Web APIにおけるデータ送受信や、設定ファイル、NoSQLデータベースなど、プログラムがデータを処理する場面で広く利用されています。構文が厳密に定義されており、多くのプログラミング言語で標準的にサポートされているため、機械によるパース（解析）や生成が容易です。
記述のしやすさ
記述のしやすさは、ドキュメント作成の効率に直結する重要な要素です。マークダウンは、#で見出し、*や-でリスト、**で太字といったように、直感的で覚えやすい記号を用いるため、非常に手軽に記述を始めることができます。覚えるべきルールも比較的少なく、プレーンテキストを書く感覚に近い形で、構造化された文書を作成できます。特別なツールを必要とせず、一般的なテキストエディタで十分に記述可能です。
YAMLは、インデントが構造を示すというルールが基本であり、括弧や引用符を多用しないため、見た目がすっきりとし、記述量も少なくなる傾向があります。特に階層構造を持つデータを記述する際には、インデントによって視覚的に構造を表現できるため、直感的に記述しやすいと感じるでしょう。ただし、インデント（スペースの数）が意味を持つため、記述ミスがエラーにつながりやすい側面もあります。また、アンカーやエイリアスといった高度な機能もあり、これらを使いこなすには学習が必要です。
JSONは、{}でオブジェクト（キーと値のペア）、[]で配列（リスト）を表現し、キーと文字列の値はダブルクォーテーション"で囲む、要素間はカンマ,で区切る、といった厳密なルールに基づいています。このルールは一貫性があり、機械にとっては解釈しやすい反面、人間が手で記述する際には、括弧の対応やカンマの有無などに注意が必要です。特にネストが深くなると、記述が煩雑になりがちです。ただし、構文がシンプルなため、基本的なルールを覚えれば記述自体は可能です。多くのエディタにはJSONの構文チェックや整形機能が備わっており、記述を補助してくれます。
ExcelやPowerPointと比較すると、これら3つのフォーマットはすべてテキストエディタで記述できるため、起動の速さや操作の軽快さといった点で優れています。特にマークダウンは、思考を妨げずに文章構造を表現できる手軽さが魅力です。
可読性
可読性は、作成されたドキュメントを他の人が理解したり、後で見返したりする際の効率に関わります。マークダウンは、記述に使われる記号が少なく、文章の流れを妨げにくいため、レンダリング（HTMLなどに変換）されていないプレーンテキストの状態でも非常に読みやすいのが特徴です。見出しやリスト、強調などが視覚的に認識しやすく、文書全体の構造を把握しやすいと言えます。
YAMLは、インデントによって構造が視覚的に表現されるため、適切に記述されていれば、データの階層関係が非常に分かりやすいです。括弧やカンマが少ないことも、すっきりとした見た目に寄与し、人間にとっての読みやすさを高めています。設定ファイルなど、キーと値の関係性が重要なドキュメントにおいて、その可読性の高さが活きます。ただし、インデントの深さが揃っていないと、構造の解釈が難しくなる可能性があります。コメントを記述できる点も、可読性を補う上で役立ちます。
JSONは、構文が厳密であるため、機械にとっては解釈しやすい一方で、人間にとっては記号（{}, [], ", ,）が多く、特にデータ量が増えたり階層が深くなったりすると、読みにくさを感じることがあります。インデントや改行によって整形されていれば可読性は向上しますが、プレーンテキストの状態ではマークダウンやYAMLほどの直感的な分かりやすさはないかもしれません。コメントを標準で記述できない点も、可読性の観点からはデメリットとなる場合があります。
ExcelやPowerPointは、WYSIWYG（What You See Is What You Get）エディタであり、見たままの形で情報を表現できるため、視覚的な分かりやすさにおいては優れています。しかし、複雑な表や図形が多用されると、かえって情報構造が掴みにくくなることもあります。テキストベースのフォーマットは、構造が明確であれば、シンプルで本質的な情報を捉えやすいという利点があります。
表現力
ドキュメンテーションにおいては、テキストだけでなく、図表や書式設定など、多様な表現力が求められる場合があります。マークダウンは、基本的なテキスト装飾（太字、斜体、打ち消し線）、見出し、リスト、引用、コードブロック、リンク、画像の埋め込みといった表現が可能です。また、拡張機能（方言）によっては、表（テーブル）、脚注、チェックリスト、数式（LaTeX）、図（Mermaidなど）なども記述できます。ただし、フォントの種類やサイズ、色、レイアウトなどを細かく指定するような、デザイン的な自由度は高くありません。あくまで文書構造を記述することに主眼が置かれています。
YAMLは、主に構造化されたデータを記述するための言語であり、テキスト装飾や図表といった視覚的な表現力は基本的に持ち合わせていません。その目的は、設定値やデータ階層を明確に記述することにあります。ただし、複数行のテキストを | や > を使って記述したり、アンカーとエイリアスを使って同じデータを再利用したりするなど、データの表現に関する機能は備えています。
JSONもYAMLと同様に、データ構造を記述するためのフォーマットであり、視覚的な表現力は持ちません。キーと値のペア、配列といった基本的なデータ構造を組み合わせることで、様々なデータを表現できますが、テキストの装飾や図の挿入などはできません。
ExcelやPowerPointは、豊富な書式設定、図形描画、グラフ作成、表計算機能などを備えており、視覚的な表現力においてはマークダウン、YAML、JSONよりも格段に優れています。複雑なレイアウトやデザイン性の高いドキュメントを作成する場合には、依然としてこれらのツールが適しています。しかし、システム開発ドキュメントにおいては、必ずしも高度な視覚表現が必要とは限らず、むしろ構造の明確さや情報の正確性が重視される場面も多いです。マークダウンの拡張機能を使えば、ある程度の図表表現も可能です。
構造化データの扱い
システム開発ドキュメントでは、設定値、パラメータリスト、APIの仕様、データ構造定義など、構造化されたデータを扱う場面が多くあります。YAMLとJSONは、まさにこのような構造化データを記述するために設計された言語です。YAMLはインデントを用いて階層構造を表現し、キーと値のペア（マッピング）、リスト（シーケンス）を直感的に記述できます。アンカーとエイリアスを使えば、データの再利用も可能です。人間にとって読みやすく、設定ファイルなどに適しています。
JSONは、オブジェクト（キーと値のペア）と配列（リスト）を明確な構文（{}, []）で記述します。データ型（文字列、数値、真偽値、null）も定義されており、プログラムによる処理を前提としたデータ交換フォーマットとして非常に優れています。多くのプログラミング言語で容易にパース・生成できるため、APIのレスポンスや設定データの保存形式として広く採用されています。
マークダウンは、本来は文書構造を記述するための言語であり、YAMLやJSONほど厳密な構造化データを扱うのは得意ではありません。リストや表（拡張機能）を使ってある程度の構造を表現することは可能ですが、ネストが深くなったり、データ型を厳密に定義したりする必要がある場合には不向きです。ただし、コードブロック内にYAMLやJSONを埋め込むことで、文書の一部として構造化データを記述することは可能です。
Excelは、セル形式で行と列を持つ表形式データの扱いに長けています。計算式や関数も利用でき、データの集計や分析も可能です。PowerPointは、箇条書きや表を使って構造を示すことはできますが、本来はプレゼンテーション用であり、厳密な構造化データの記述には向きません。YAMLやJSONは、特に階層構造を持つデータや、プログラムで処理することを前提としたデータの記述において、Excelよりも柔軟かつ汎用性が高いと言えます。
ツール連携
ツールの連携は、ドキュメント作成・管理の効率化において重要です。マークダウンは非常に多くのツールでサポートされています。VS Code、Atom、Sublime Textなどの高機能テキストエディタには、シンタックスハイライトやリアルタイムプレビュー機能が搭載されています。GitLab、GitHub、Bitbucketなどのバージョン管理プラットフォームでは、リポジトリ内のマークダウンファイル（特にREADME.md）が自動的にレンダリング表示されます。Pandocのようなツールを使えば、HTML、PDF、Word文書など、様々な形式への変換が可能です。Jekyll、Hugo、Gatsbyなどの静的サイトジェネレータもマークダウンをコンテンツ記述言語として採用しており、ドキュメントサイトの構築が容易です。PlantUMLやMermaidといったツールと連携すれば、テキストから図を生成することもできます。
YAMLも多くのテキストエディタでシンタックスハイライトがサポートされています。設定ファイルとして広く使われているため、Docker、Kubernetes、Ansible、各種CI/CDツール（GitHub Actions, GitLab CIなど）がYAML形式の設定ファイルを採用しており、これらのツールとの連携は非常にスムーズです。プログラムからも、多くの言語でYAMLをパース・生成するためのライブラリが提供されています。
JSONは、Web開発における標準的なデータ交換フォーマットであるため、ほぼ全てのプログラミング言語でネイティブまたはライブラリによるサポートがあります。テキストエディタやIDE（統合開発環境）でのサポートも充実しており、構文チェック、整形、折りたたみ機能などが利用できます。Webブラウザの開発者ツールでもJSONデータの表示やデバッグが容易に行えます。PostmanのようなAPI開発ツールでもJSONは中心的な役割を果たします。
ExcelやPowerPointは、Microsoft Office製品群との連携は強力ですが、開発ツールやバージョン管理システムとの直接的な連携は限定的です。テキストベースのフォーマットは、コマンドラインツールやスクリプトとの連携が容易であり、ドキュメント生成や検証の自動化といった点で有利です。
学習コスト
新しいツールや記法を導入する際には、学習コストも考慮すべき点です。マークダウンは、基本的な記法が非常にシンプルで直感的であるため、学習コストは極めて低いと言えます。数時間程度で基本的な書き方を習得し、実用的な文書を作成し始めることが可能です。拡張機能（方言）まで含めると覚えることは増えますが、基本的な機能だけでも十分に役立ちます。
YAMLは、インデントによる構造表現という基本的なルールを理解すれば、読み書きを始めること自体は難しくありません。しかし、インデントの扱いやデータ型、アンカー・エイリアスなどの高度な機能を正確に理解し、使いこなすには、マークダウンよりは学習が必要です。特にインデントのエラーは初心者がつまずきやすいポイントです。
JSONは、構文ルールが厳密ですが、そのルール自体は比較的少ないため、基本的な構造（オブジェクト、配列、キーと値、データ型）を理解すれば、読み書きは可能です。ただし、括弧の対応やカンマの有無など、細かいルールを正確に守る必要があり、慣れるまではエラーに悩まされるかもしれません。プログラミング経験があれば、JavaScriptのオブジェクトリテラルに似ているため、比較的容易に習得できるでしょう。
ExcelやPowerPointは、多くの人が基本的な操作に慣れ親しんでいるため、導入のハードルは低いかもしれません。しかし、高度な機能（マクロ、複雑な関数、ピボットテーブルなど）を使いこなすには相応の学習が必要です。マークダウン、YAML、JSONは、特に開発者にとっては学習コストが比較的低く、開発ワークフローに組み込みやすいと言えます。
バージョン管理のしやすさ
システム開発において、ドキュメントの変更履歴を管理し、共同作業を円滑に進めるためには、バージョン管理システム（Gitなど）との親和性が重要です。マークダウン、YAML、JSONはすべてプレーンテキスト形式であるため、Gitとの相性が抜群です。変更箇所が明確に行単位で記録され、差分（diff）の確認が非常に容易です。誰が、いつ、どこを、どのように変更したのかを正確に追跡できます。ブランチ機能を使って複数の変更を並行して進めたり、マージ機能を使って変更を統合したりすることもスムーズに行えます。コンフリクトが発生した場合も、テキストベースであるため、手動での解決が比較的容易です。
一方、Excel（.xlsx）やPowerPoint（.pptx）のファイルは、実体はXMLベースの構造を持っていますが、基本的にはバイナリファイルとして扱われることが多く、Gitで差分を分かりやすく表示するのは困難です。変更箇所を特定するのが難しく、コンフリクトが発生した場合の解決も複雑になりがちです。SharePointなどの専用システムを使えばバージョン管理は可能ですが、Gitを中心とした開発ワークフローとは別に管理する必要が出てきます。
テキストベースのフォーマットを採用することは、コードとドキュメントを一元的にバージョン管理できるという大きなメリットをもたらし、開発プロセス全体の整合性を高める上で非常に有効です。特に、ドキュメントがコードと密接に関連する場合（API仕様書、設定ファイルの説明など）には、この利点が顕著になります。
生成AIとの親和性
直近生成AIの進化が目覚ましく、ドキュメント作成の支援ツールとしての活用が期待されています。生成AIは、テキストデータの処理を得意としており、プレーンテキスト形式であるマークダウン、YAML、JSONとの親和性は非常に高いです。AIに対して、特定の要件に基づいたドキュメントの草案作成を指示したり、既存のドキュメントの要約や翻訳、構成の改善、誤字脱字のチェックなどを依頼したりすることが可能です。
マークダウンは、自然言語に近い形で文章構造を表現できるため、AIが内容を理解しやすく、人間が読むような自然な文章の生成に適しています。例えば、「○○機能の概要をマークダウンで書いて」といった指示で、基本的なドキュメントを生成させることができます。
YAMLやJSONは、構造化データを扱うため、AIに対して特定のフォーマットに基づいた設定ファイルやデータ構造の生成を指示するのに適しています。「指定したパラメータを持つKubernetesのDeployment設定をYAMLで生成して」や、「ユーザー情報を表すJSONスキーマを作成して」といった具体的な指示が可能です。また、既存のYAML/JSONファイルの内容を説明させたり、エラー箇所を特定させたりといった活用も考えられます。
ExcelやPowerPointのファイルは、バイナリ形式や複雑なXML構造を持つため、AIが直接内容を正確に解析し、編集・生成することは、テキストベースのフォーマットに比べて困難です。テキスト情報を抽出することは可能ですが、レイアウトや書式、埋め込まれたオブジェクト（図形、グラフなど）の情報まで含めて完全に理解し、意図通りに操作することは難しい場合があります。
したがって、将来的に生成AIを活用してドキュメント作成・管理の効率化を図る上では、テキストベースのフォーマットであるマークダウン、YAML、JSONを選択することが有利になると考えられます。
ドキュメントの種類との適合性
各フォーマットは、その特性から、特定の種類のドキュメントに適しています。
マークダウンは、その記述の手軽さと可読性の高さから、文章中心のドキュメント全般に適しています。具体的には、READMEファイル、開発ブログ、議事録、簡単なマニュアル、Wikiページ、技術仕様書の概要部分などが挙げられます。拡張機能を使えば、簡単な表や図を含む設計書やレポートにも利用できます。構造化された文章を素早く書きたい場合に最適です。
YAMLは、人間が読みやすい構造化データ表現に優れているため、設定ファイルの記述に最も適しています。Docker Compose、Kubernetesマニフェスト、Ansible Playbook、CI/CDパイプライン定義、アプリケーションの設定ファイルなどが代表例です。階層構造を持つデータや、設定パラメータをリストアップするようなドキュメントにも向いています。APIのスキーマ定義（OpenAPI Specificationなど）でも利用されます。
JSONは、機械による処理を前提とした厳密なデータ構造定義とデータ交換に適しています。Web APIのリクエスト/レスポンスボディ、設定ファイル（特にプログラムから読み込むことを主目的とする場合）、データのエクスポート/インポート形式、NoSQLデータベースのドキュメント形式などに広く利用されます。API仕様書の一部として、リクエスト/レスポンスの例を示す際にも使われます。
システム開発のドキュメンテーションにおいては、これらのフォーマットを適材適所で使い分けることが有効です。例えば、プロジェクト全体の概要や基本的な使い方をマークダウンで記述し（README.md）、アプリケーションの設定はYAMLで管理し（config.yaml）、APIのデータ形式はJSONで定義する（API仕様書内）、といった使い分けが考えられます。Excelは、複雑な計算やデータ分析が必要なテスト仕様書や課題管理表などに、PowerPointは、図解を多用するシステム構成図や画面遷移図、プレゼンテーション資料などに、依然として有効な場合があります。
Excel/PowerPointとの比較（改めて）
これまでの比較を踏まえ、マークダウン、YAML、JSONとExcel/PowerPointのメリット・デメリットを再整理します。
マークダウン、YAML、JSON（テキストベースフォーマット）のメリット:
- バージョン管理: Gitとの親和性が高く、変更履歴の追跡や差分確認、マージが容易。
- 軽量性・ポータビリティ: ファイルサイズが小さく、特定のアプリケーションに依存しないため、環境を選ばずに扱える。
- 編集の容易さ: 多くのテキストエディタで手軽に編集でき、起動も速い。
- ツール連携: 開発ツール、CI/CDパイプライン、静的サイトジェネレータなど、様々なツールと連携しやすい。
- 再利用性: テキストベースであるため、スクリプト等での処理や他ドキュメントへの埋め込みが容易。
- 生成AIとの親和性: AIによる内容の解析、生成、編集がしやすい。
- 構造化: YAML/JSONは構造化データの記述に特化。マークダウンも基本的な文書構造を表現可能。
マークダウン、YAML、JSON（テキストベースフォーマット）のデメリット:
- 視覚的な表現力: Excel/PowerPointに比べ、複雑なレイアウト、デザイン、図形描画、グラフ作成能力は低い。
- WYSIWYGではない: 記述内容と最終的な表示結果が異なる場合がある（特にマークダウンのレンダリング）。
- 学習コスト: 記法やルールを覚える必要がある（ただし、Excel/PowerPointの高度な機能よりは低い場合も）。
- 非ITユーザーの慣れ: Excel/PowerPointに慣れているユーザーにとっては、導入に抵抗がある可能性がある。
Excel/PowerPointのメリット:
- 視覚的な表現力: 豊富な書式設定、図形、グラフ機能により、デザイン性の高いドキュメントを作成可能。
- WYSIWYG: 見たままの形で編集・表示できる。
- 普及度・慣れ: 多くのビジネスユーザーが基本的な操作に慣れている。
- 表計算機能 (Excel): 複雑な計算やデータ分析が可能。
Excel/PowerPointのデメリット:
- バージョン管理: Gitでの差分管理が困難。
- ファイルサイズ: テキストベースに比べファイルサイズが大きくなりがち。
- 特定のアプリケーション依存: 専用のソフトウェアが必要。
- ツール連携: 開発ツールとの連携が限定的。
- 再利用性: テキストとしての再利用性が低い。
- 生成AIとの親和性: AIによる内容解析・編集がテキストベースより困難。
おわりに
いかがでしたか。私個人の考えとしては、今後AIとの協業が強まると考えており、アウトプットは特に文字情報についてはテキスト出力が望ましいのではと考えています。みなさんのマークダウン、YAML、JSONを深掘りするキッカケにしていただけると幸いです。
アクセンチュア株式会社に所属する社員有志による運営です。アクセンチュアの社員による様々な発信をまとめています。なお、投稿内容は社員個人の見解であり、所属する組織を代表するものではありません。
Discussion