「テキストベース文書によるドキュメント作成」

テキストベース文書とは、プレーンテキストで記述された文書です。プレーンテキストは、文字コードに基づく文字や改行のみで構成されたテキスト形式のことで、文字の装飾や画像、レイアウト情報などは含まれません。そのため、軽量で扱いやすく、差分比較や検索、再利用に適しています。

プレーンテキストは、メモ書きや、プログラムの説明を記述したREADMEファイルなどで広く利用されてきました。また、プログラムのソースコードもプレーンテキストで記述されており、ソフトウェア開発では最も身近なファイル形式の一つと言えます。

ただし、プレーンテキストだけでは文字の装飾やレイアウトを表現できないため、仕様書や設計書などのドキュメント作成では、Wordをはじめとするオフィスソフトが広く利用されてきました。

しかし近年では、プレーンテキストに簡単な記法を追加することで、読みやすく構造化された文書を作成できるようになり、テキストベース文書の活用が広がっています。

プレーンテキストの扱いやすさを維持したまま、読みやすい文書を作成できるようにしたものがMarkdownです。

Markdownは軽量マークアップ言語の一つであり、見出しや箇条書き、表、コードブロックなどを簡潔な記法で記述できます。記述したテキストは、Markdown対応エディタやGitHub（Gitを利用したソースコード共有サービス）などで整形された文書として表示されるため、プレーンテキストでありながら、構造化された読みやすい文書を作成できます。

そのため、READMEファイルや技術資料、設計書など、ソフトウェア開発におけるさまざまなドキュメントの作成に活用できます。

以下に、左側へテキストエディタで作成したMarkdown文書、右側へその文書をMarkdownビューワーで表示した結果を示します。

テキストエディタで作成したMarkdown文書	Markdownビューワーで表示した結果
# UART通信仕様 ## 通信規約 - 通信速度：9600bps - データ長：8bit - パリティ：奇数 - ストップビット：1bit ## 通信フレーム |制御キャラクタ|コード(HEX)|内容| |---|---|---| |STX|02|フレーム先頭| |ETX|03|フレーム終端| ## サンプルコード ```c void Uart_Send(uint8_t data) {   ... } ```

図 1 Markdown文書の記述例と表示例

Markdownが文書を構造化して記述するための軽量マークアップ言語であるのに対し、PlantUMLやMermaidは図をテキストで記述するためのツールです。

PlantUMLとMermaidは、どちらも専用の記法を記述するだけで図を自動生成でき、フローチャートやシーケンス図、状態遷移図など、さまざまな種類の図を作成できます。

PlantUMLはクラス図などを含むUML図（ソフトウェア設計を表現するための標準的な図）に幅広く対応しています。また、Mermaidもフローチャートやシーケンス図、状態遷移図などを作成できるほか、Markdown文書へ直接記述でき、対応したツールでは図として表示できるため、文書と図を一体で管理しやすいことが特徴です。

図をテキストとして記述できるため、仕様変更時にはテキストを修正するだけで図を更新でき、設計書の保守性向上や更新作業の効率化にも役立ちます。

以下に、左側へシーケンス図を記述したPlantUMLコード、右側へそのコードをPlantUMLビューワーで表示した結果を示します。

PlantUML形式で記述したテキスト	生成された図
@startuml title UART通信シーケンス participant マイコン participant UARTドライバ participant 外部機器 マイコン -> UARTドライバ : 送信要求 UARTドライバ -> 外部機器 : コマンド送信 外部機器 --> UARTドライバ : 応答 UARTドライバ --> マイコン : 受信通知 @enduml

図 2 PlantUMLによるシーケンス図の記述例と生成結果

続いて、PlantUMLと同じ内容のシーケンス図をMermaid形式で記述した例を示します。左側へMermaidコードを記述したMarkdown文書、右側へその文書をMarkdownビューワーで表示した結果を示します。

Mermaid形式で記述したテキスト	生成された図
# UART通信シーケンス ```mermaid sequenceDiagram      participant マイコン      participant UARTドライバ      participant 外部機器      マイコン->>UARTドライバ: 送信要求      UARTドライバ->>外部機器: コマンド送信      外部機器-->>UARTドライバ: 応答      UARTドライバ-->>マイコン: 受信通知 ```

図 3 Mermaidによるシーケンス図の記述例と生成結果

Gitをはじめとするバージョン管理システムは、ソースコードの変更履歴を管理するために広く利用されています。テキストベース文書はソースコードと同じプレーンテキストで構成されるため、ソースコードと同様にバージョン管理できます。

そのため、変更履歴の記録や差分比較、レビューを効率よく行えます。また、ソースコードとドキュメントを同じリポジトリ（Gitで管理するプロジェクト単位の保存場所）で管理できるため、設計書とソースコードの整合性を維持しやすいという利点もあります。

以下に、GitHubでMarkdown文書の変更点（通信速度とパリティを変更）を差分表示した例を示します。

Markdownの変更点をGitHub上で確認

図 4 GitHubによるMarkdown文書の差分表示例

プレーンテキストは特定のアプリケーションに依存しないため、Windows標準のメモ帳をはじめ、多くのテキストエディタで編集できます。そのため、WindowsやmacOS、Linuxなど異なる開発環境でも同じ文書を容易に共有・編集できます。

また、テキストエディタでは文書の追記や修正だけでなく、検索や置換も容易に行えるため、大量のドキュメントの保守にも適しています。

PlantUMLやMermaidでは、図をテキストで記述して生成するため、仕様変更時にはテキストを修正するだけで図を更新できます。図形の位置合わせや線の引き直しを行う必要がなく、変更履歴もGitで管理しやすいことが特徴です。

生成AIはプレーンテキストを扱うことを得意としており、Markdownなどのテキストベース文書は、そのまま生成AIへ入力して要約やレビュー、文章作成などに活用できます。

また、PlantUMLやMermaidについても、作成したい図の内容を生成AIに指示することで、図を生成するためのコードを作成できます。そのため、PlantUMLやMermaidの記法をすべて覚えていなくても、生成AIを活用することで効率よく図を作成するためのコードを生成できます。

以下は、生成AIへ「ストップウォッチの状態遷移図をPlantUMLで作成してください」と依頼した例です。左側へ生成AIとのやり取り内容、右側へ生成されたPlantUMLコードを対応ツールで表示した状態遷移図を示します。

生成AIとのやり取り	生成された状態遷移図

図 5 生成AIによる状態遷移図の作成例

MarkdownやPlantUML、Mermaidは専用の記法で記述するため、基本的な記法を習得する必要があります。学習コストは比較的低いものの、記法を知らない人にとっては、文書の編集や保守の負担となる場合があります。

テキストベース文書はソフトウェア開発では広く利用されていますが、テキストベース文書に馴染みのない利用者にとっては、WordやExcelの方が扱いやすい場合があります。そのため、社外へ提出する文書や、多くの関係者が扱う文書では、オフィス文書の方が適している場合もあります。

Markdown文書を見やすく表示したり、プレビューを確認しながら効率よく編集したりするには、Markdown対応のエディタを利用することが一般的です。また、閲覧のみを行う場合でも、Markdown対応のビューワーが必要になることがあります。

なお、Windows標準のメモ帳もバージョン11.2504.52.0からMarkdown形式に対応しました。ただし、対応している機能は基本的なものに限られ、専用エディタと比べると編集支援機能などには制限があります。そのため、本格的な文書作成にはVisual Studio CodeなどのMarkdown対応エディタを利用することをおすすめします。

Markdownは文書構造を記述することを目的としているため、WordやExcelのような自由なレイアウトや細かな位置調整には向いていません。また、Markdownでは基本的な表は作成できますが、セル結合や数式、複雑なレイアウトには対応できず、集計やグラフ作成などの機能も備えていません。そのため、表計算やデータ分析を行う用途ではExcelの方が適しています。

さらに、PlantUMLやMermaidでは、表現できる図の種類や表現方法には制約があり、複雑な図面やイラストを作成する場合には、Visioやdraw.ioなどのGUIツールの方が適しています。

また、Markdown文書はPDFへ変換できますが、改ページやレイアウトの細かな調整には限界があります。見栄えや印刷レイアウトが重視される文書では、WordやExcelの方が適しています。