Markdownは情報に「かたち」を与える道具である

1. Markdownってなんなんだ？

1.1 まずは、ただの書き方である

Markdown（マークダウン）とは、プレーンテキスト形式で書式付きテキストを記述する軽量マークアップ言語である。

(出典: Markdown - Wikipedia)

平たく言うと、WordとかExcelを使わずに、章・節・項とか、箇条書きとか、表なんかを書くための 「お作法」 である。(まぁ、Excelはそもそも文書作成のためのツールじゃないけど)

綺麗に表示するには専用のツールが必要になるけど、そのままでも、割と「それっぽく」見える。

例えば、こんな感じ。

## 1. Markdownってなんなんだ？
### 1.1 まずは、ただの書き方である
> Markdown（マークダウン）とは、プレーンテキスト形式で書式付きテキストを記述する軽量マークアップ言語である。

_(出典: [Markdown - Wikipedia](https://ja.wikipedia.org/wiki/Markdown))_

平たく言うと、WordとかExcelを使わずに、章・節・項とか、箇条書きとか、表なんかを書くための **「お作法」** である。(まぁ、Excelはそもそも文書作成のためのツールじゃないけど)

普通の文章に「見出しです」「引用です」「リンクです」という簡単な記号を足すだけ。難しいコマンドを覚えたり、複雑な構文を覚える必要はない。
この書いていて「それっぽく」見えるところがとても良いところで、文章を書くときに、記法が思考を邪魔しない。ほぼ文章に集中できて、でも、ちゃんと文書として体裁が整う。

正直、Markdownの表示に対応していないエディタでMarkdown記法を使っても、そのまま普通に読めてしまうし、動きが軽いので下手にWordなんかのオフィス・ツールを使うよりもストレスがない。

それでも「整った見た目」が気になる場合は、良いツールがWeb上に沢山ある。(例えばボクはよく HackMD というツールを使ったりする)
書き倒していくうちにWeb上のツールでは物足りなくなってきたら、有償のツールを使ってもいい。ボクはMWebというツールを愛用していて、実はこのblogを再開してから、記事は全部、これで書いている。（Mac/iOS限定になっちゃうけど。）

1.2 Markdownは、思ったよりずっと簡単である

Markdownの記法はたくさんあるが、実際によく使うものは多くない。

見出し、箇条書き、表、引用、コードブロックくらいを知っていれば、かなりの文章は書ける。それぞれこんな感じ。

• # をつけると見出し
• - をつけると箇条書き
• 1. 2. と書くと番号付きリスト
• > をつけると引用
• | で区切ると表

列1	列2
foo bar	hogehoge

実際のMarkdownはこんな感じ。

|列1　|　列2　|
|---|---|
|foo bar　|　hogehoge　|

• inline command のように、文章の中でコードやコマンドっぽいものを示したいときは、バッククォート1個で囲む
• コードブロック（この中に書いてあるのはコードだよ、という段落）は ``` で囲む

コードブロック（この中に書いてあるのはコードだよ、という段落）は ```で囲む

とても簡単だ。

しかも、現代は、Markdownの書き方を暗記する必要もない。書き方忘れたら、AIに頼めばいい。

• この文章をMarkdownにしてください
• 表にしてください
• 見出しをつけてください

これだけ。もともとの記法がシンプルで、そのままでも「それっぽい見た目」なので、何度か頼んでるうち、自然に覚えてしまう。

1.3 だから、Markdownは怖くない

Markdownは、プログラミングではない。特殊なソフトも必須ではない。
書くだけならメモ帳で十分書ける。

購入コスト0、学習コストもほぼ0である。

今日から試せるし、「なんか違う」と思ったら投げ出しても良い。
損するものがあるとしたら、試してみたあなたの時間だけど、これだけ学習コストが低いと、ほぼ無視できるくらい。

というか、そこまでコスパが気になるなら新しいことは試さない方がいい。

2. でも、Markdownはエンジニア文化の道具だった

2.1 エンジニアは、ドキュメントも生きた状態で管理したかった

ソースコードのように、ドキュメントも変わり続ける。
システムの仕様、手順書、設計メモ、READMEなどは、一度作って終わりではない。
変更され、修正され、更新され続ける。

しかもプロにとっては、ソースコードより、なんならドキュメントの方が価値が高い。
ソースコードは「どのように動いているか」は教えてくれるが、「どうしてそうなのか」を教えてくれることはほぼないから。
この「どうして」をソースコードから再現するコストは、とってもお高いので。

だから、差分を見たい。

• どこを変えたのか
• 誰が変えたのか
• なぜ変えたのか
• いつ変えたのか

それさえ分かれば、どこを・どう見たらいいか、プロはすぐに判断できる。
それで、履歴を追うために、テキストで書ける文書形式は都合がよかった。

なにしろテキストファイルなら、ソースコードと同じように扱えて、比べられる。ついでに言えば、ちょっと思いついたときに、その場にあるありあわせのツール（なんならメモ帳でもいい）で読み書きできる。

ついでに自慢じゃないが、エンジニアはソースコードを扱うのが大得意だ。
そのやり方も、ツールも、共通の文化も、だいたい出来上がっている。ソースコードと同じように管理できるなら、面倒くさいドキュメント管理も苦じゃなくなる。

だからエンジニアはドキュメントも、ソースコードと同じように扱いたかった。

そうしてMarkdownはエンジニアたちに人気になった。

なにしろ新しいプログラム言語を覚えるよりも、ずっと簡単だ。なんならWordの使い方を覚えるよりも簡単だ。
しかもプログラムを書ける環境があれば、同じ環境で、そのままドキュメントも書ける。
そのくせ、エンジニアがドキュメントを書く時に使いたい表現は、だいたい扱える。

2.2 あんまり気に入ったので「図」も書きたくなった

なにぶん、長い文章は書くのも大変だし、読むのはもっと大変だ。
そういう時は「図」で表現すると、読むのも書くのも簡単だ。いっぱい文字を並べなくてもいい。

ついでにいうとフローチャートやらクラス図やら、エンジニアたちは何かと図を書く機会が多いし、なんなら言葉よりも図が会話の中心になったりする。

でも、そのためにWordやPowerPointやVisioを開いたり、その他、色々なツールを開いたりするのは面倒だった。
もっと嫌なのは、そうして書いた図をドキュメントに貼り付けるのが、たいそう面倒くさいことだった。
もっともっと嫌なのは、そうやって書いた図とは別に図の変更履歴を書き残さなくちゃいけないのが、めちゃめちゃ面倒くさいことだった。

だからエンジニアたちは思ったんだね。

図もマークダウンで書けばいい

幸いなことに、そういう仕様を作ったり、その仕様通りに動くツールを作ったりすることは、彼らの得意分野だった。なにしろ、その道のプロなので。

そうして生まれた「図を書くため」のMarkdownの一つがMermaidだ。

graph TD
図を書きたい --> でも別のソフトを使うのは面倒 --> 図もマークダウンで書けば良い --> 作っちゃったっ

こんな風に書くと、こうなる。

graph TD
図を書きたい --> でも別のソフトを使うのは面倒 --> 図もマークダウンで書けば良い --> 作っちゃったっ

2.3 へー、エンジニアの道具なのね

…そう思って、この記事をそっ閉じしたら、大損である。

ドキュメントを書くのも管理するのも、エンジニアの専売特許じゃない。

動作が軽くてサクサク動くのは、常に正義だ。（パソコンの反応が遅いのにイライラしたことのない現代人は幸いである…）

しかも、変更履歴を管理したりする面倒くささも、エンジニアの仕事に限ったことじゃない。複数人で作業してて、どれが最新だか訳わかんなくなったり、誰が加えたかもしれない間違った変更を元に戻すのに苦労した経験がある人は少なくないはずだ。
そして、Markdownでドキュメントを書いたなら、それを上手く扱うツールはすでにエンジニアが用意してくれていて、しかも常にカイゼンしてくれている。何しろ欲しい人たちが使い倒しながら作ってるので、とっても洗練されている。

しかも、だ。

生成AIはテキストを扱うのが とっても得意 なのである。PDFよりもWordよりもPowerPointよりも、生成AIはテキストファイルがダイスキだ。

3. 生成AI時代には話が変わる

3.1 生成AIは賢いが、何でも得意なわけではない

生成AIは賢いので、頼めば仕事の8割くらいはこなしてくれる。PowerPointの資料だってWordドキュメントだって作ってくれるし、長いながいPDFドキュメントの要約だってしてくれる。
でも思ったことはないだろうか？

「思ってたんと、なんか違う」
「いちばん汲み取って欲しいところを外している」

生成AIがアホの子だからだろうか？ もちろん、そんなことはない。

単にPowerPointもWordドキュメントも、PDFファイルも、生成AIにとってはちょっと苦手なところがある相手だからだ。
苦手でもおニンゲンさんが頼むので、頑張ってくれているだけなのだ。
なんて健気な…

3.2 生成AIは何が苦手なのか？

総括的にいうと生成AIは 「意味の手がかりが少ないもの」 が苦手だ。はっきりと書いてあること を書かれたまま読むことは得意だけど、空気は読めない。

「これは何なのか」「どこが重要なのか」「何と何が関係しているのか」が、文書の中にはっきり書かれていないドキュメントには、その補助線が必要になる。
補助線がない時には、頑張って想像したり推測して読み取るのだけど、どうしても 「思ってたんと、なんか違う」 が起きがちだ。

• 画像データ
  • 画像として渡された図は、生成AIにとってはまず「絵」である
  • 形状はよく分かるけど、その意味はよく分からない
  • 箱、矢印、文字、位置関係を読み取り、そこから意味を推測しなければならない
• レイアウトで意味を伝えている資料
  • 大きな文字、太字、色、配置、余白、吹き出し、囲み線などで意味を伝えている
  • 人間はそれを見た目から自然に読み取る
  • しかし生成AIは、そこに込められた意図を推測する必要がある
• 長い文章
  • 長い文章も、まとまりが見えないと推測が必要になる
  • 見出しのない長文では、どこで話題が変わるのか、何が結論なのか、何が補足なのかを推測しないといけない

要するに、おニンゲンさんたちは、自分で思ってる以上に「見た目」から、いろんなことを補完している。
でも、生成AIにとって、そういう補完は、とっても苦手なのだ。だって空気読めない子なので。

文字は読める。
共有された範囲での文脈もけっこう読める。

だけど、画像やレイアウトで伝えている情報、まとまりが明記されていない長い文章は、あんまり得意じゃない。そして、PowerPointもWordドキュメントも、そういう風に作られているものがとっても多い。
だから、PDFファイルも、生成AIにとっては「そのまま意味が取り出せるもの」ではない。
それで見た目を読み取り、配置を読み取り、図の関係を読み取り、文脈を補いながら「たぶんこういう意味だろう」と推測している。

推測が増えれば、それだけ結果はブレる。量が増えれば、小さなブレが大きくなる。必然である。

3.3 Markdownは、生成AIに「意味の目印」を渡せる

じゃ、どうすりゃいいのか？

• これは見出しです
  • ここから次の見出しまでは、だいたい一つのまとまりです
• これは箇条書きです
  • 箇条書きで並んでいるのは同列の項目です
  • 段下げしてあるのは上の項目の一部です
• これは表です
  • 行と列で読んでください
• これは図です
  • この図のこの要素は、別のこの要素と繋がっています
  • これはガントチャートで、このタスクはいついつから、いついつまでの期間です
  • …などなど

こういうことを生成AIに教えてあげる印付け、マーキングをしてあげればいい。それだけで「これは何なのか」「どこが重要なのか」「何と何が関係しているのか」が生成AIに分かりやすくなる。

で、ここでMarkdownの出番である。

最初に紹介したように、シンプルな記号でマーキングができる。軽量・シンプルで、人間の目にも「それっぽく見える」から、ストレスが少ない。それでいて、生成AIにとっても、マークの意味が明確だ。
書き方の「お作法」も、だいたい決まってるので、いちいち生成AIに記号の意味を教えてあげる必要はない。生成AIにとってそれは「空気」で推測するものじゃなく、「常識」として知っていることだ。

さっき紹介したMermaidなら、図の中身の一つ一つまで、事細かに教えてあげられる。表示されるのは「絵」だけど、マークダウンそのものは「意味」のカタマリだ。

4. でもやっぱり、実はMarkdownは難しい

4.1 難しいのは「お作法」じゃない

ここまでさんざん、簡単だって紹介しといてなんだけど。実は、ちゃんとしたMarkdownを書くことは、人によっては 難しい。

でも難しいのは「お作法」じゃない。
シンプルで覚えることも多くないし、特別なツールもいらない。ビューワーを使わなくても「それっぽい」見た目になるから、書いててストレスも少ない。

本当に難しいのは…

• これは見出しです
  • ここから次の見出しまでは、だいたい一つのまとまりです
• これは箇条書きです
  • 箇条書きで並んでいるのは同列の項目です
  • 段下げしてあるのは上の項目の一部です
• これは表です
  • 行と列で読んでください
• これは図です
  • この図のこの要素は、別のこの要素と繋がっています
  • これはガントチャートで、このタスクはいついつから、いついつまでの期間です
  • …などなど

こういうことを考えながら、伝えたいこと・書きたいことを整理して、かたちを整えることだったりする。

• それが何なのか
• どんな要素でできているのか
• 何と何がつながっているのか
• どう読んでほしいのか

これをかたちにするのが難しい。

4.2 「かたち」を与えることを構造化という

「かたち」を与えることを構造化という。

• そもそも、この文章は何について書いているのか
• どこからどこまでが一つのまとまりなのか
• 何が重要なのか
• 何と何がつながっているのか
• どう読んでほしいのか

こういうことを考えながら、伝えたいこと・書きたいことを整えることだと思ってくれればいい。だいたいそれで合っている。

で、どういうことかは難しくない。でも、実際にやってみると手が止まりがちになる。

でも大丈夫。ちょっとしたコツがある。
これさえ知ってれば、すぐに出来るようになるという類のコツじゃないけど。でも、意識してやってれば、そのうち確実に上手になる類のコツだ。

5. 構造化とは「分ける・並べる・名づける・つなぐ」こと

5.1 とりあえず、4つだけ覚えてくれ。以上。

4つだけ覚えてくれればいい。

1. 分ける
2. 並べる
3. 名づける
4. つなぐ

これだけ。でも、このたった4つを意識してやってみるだけで、なんとなく「かたち」が整いはじめるはずだ。

このあたりのやり方はエンジニアのための図解思考 再入門講座 情報の“本質"を理解するための実践テクニックに詳しく丁寧に書かれている。
なので、この記事を読んで興味を持ったら、読んでみて欲しい。

5.2 分ける

大きなものを大きいままにするから、分かりづらい。
これって実は生成AIに限ったことじゃなくて、人間でも同じこと。

だから小さいカタマリに分けていく。
長い文章、会議メモ、業務手順、アイデアメモを、まず小さなまとまりに分けるところから始めてみようか。たぶん、日常的によくやることだろうから。

最初は感覚でいい。

まずは1文ずつに分けてみる。長い1文だったら2つか3つに分けられないか試してみる。さらにイケそうなら、「誰が」「何を」「どうした」くらいまで分けてみる。なんだかまだまだイケそうな気がしたら、単語か文節単位まで分けてみる。
例えば。

• 1文ずつに分ける
• 長い1文を2つか3つ
• 単語単位
• 文節単位

こんな感じでいい。
要するに箇条書きにしてみる。

5.3 並べる

分解したら並べてみよう。
並べ方には色々あるけど、だいたいはこんな感じかな。

• 似たものを近くに、似てないものを遠くに並べてみる
  • 似たものを近くに並べると、その中でも似たものと似てない物が出てくる
  • そうしたら、もう一回並べ直してみる
  • 近くにいるもの同士は、たぶん、仲間（＝ひとまとまり）だ
• 順番に並べてみる
  • 大きいものから小さいものとか
  • あいうえお順とか
  • 最近のことから昔のこととか
  • 手順の最初から終わりにとか

似たものと似てないものを並べ直してみるのは、実は「分ける」と同じことをやっている。似ているものを「まとめる」のも「分ける」ことと同じだ。

順番に並べるのは、実は分けたものの間の関係を、なんとなく整えている段階だ。
いろいろな並べ方を試してみるといい。そうすると、やっぱり「似てるもの」（だいたい同じ大きさとか）が近くに並んだり、左から右みたいに順序が見えたり、これがあってあれがあるみたいな繋がりが見えたりと、いろいろ発見がある。

5.4 名づける

似たものをまとめたら、まとまりに名前を付けよう。
なにしろ名前がないと、扱いづらい。

それに名前がないままだと、「なんか同じような話が集まっているところ」でしかない。
でも名前をつけると、「課題」「原因」「対応策」「次にやること」みたいに、ひとまとまりの情報として扱えるようになる。

順番でまとまりを作った場合は、番号を付けてもよい。第1グループ、第1章、1巡目…とかね。

並べ方のルールを2つ組み合わせると表になったりする。

すいへーりーべ…でお馴染みの周期表（最近、言わないかな？）も、そうやってできている。縦は性質の似ている元素が並び、横方向は陽子の数に並ぶ。1行単位に「周期」が出来る表なので、周期表というわけ。
つまり表というのは、ただマス目に情報を置いたものではなく、「どう並べるか」によって意味が生まれる道具でもある。

5.5 つなぐ

最後はつなぐ。

並べてみた「まとまり」と「まとまり」をつなげてみる。
つなげてあげることで、いったんバラバラにしたものが、また全体に戻る。

• 順序
  • 左から右とか、小さいものから大きいものとか、前工程と後工程とか
  • とにかく順序が大事なつながり
  • 文章なら1章から2章、図なら矢印の左右や上下になる
• 因果/依存
  • 原因と結果、AだからBみたいな
  • 他にも前提条件みたいに、AがあるからBが…みたいな関係
  • 文章だとAゆえにB、図だとこれも矢印の左右や上下で書かれることが多い
• 親子関係
  • Aの中にB,C,Dがある
  • 大きなまとまりと、その中身の関係
  • 文章だと1章1節1項みたいにまとまったり箇条書きの中でインデントしたり、図なら円/箱の中に小さい円/箱みたいに書いたりすることが多い
• 割り当て
  • AさんがBを担当する、とか
  • この資料はこの作業で使う、とか
  • 文章だったら最初の「分ける」で触れた「誰が」「何を」「どうした」みたいになる（もっとちゃんとやると5W1Hになる）けど、図で書く時の表現はそれこそ色々

他にも、いろんな「関係」を作ることができる。このあたりは、エンジニア御用達のUMLとか、いろんなお手本があるから、もっと知りたくなったら見てみると良いと思う。

5.6 大変そうだと思ったら、まずは雑にやってみるといい

とりあえず「分ける」「並べる」「名づける」「つなぐ」を雑にやってみればいい。

graph LR
    divide[分ける]
    layout[並べる]
    name[名づける]
    link[つなぐ]
    
divide --> layout --> name --> link 

たぶん最初にとっつきがいいのは、箇条書き。

何がいいって、雑にやっても形になる。直すのも楽だし。
思いつきでだらだら書いた文章も、とにかく必死で書き留めたメモも、箇条書きにしてみるだけで「かたち」を持ち始める。

そして「かたち」を持つことで解像度が上がって、もっといい「かたち」が見えてくる。

それでも大変そう？ 生成AIに頼んでみたらいいんじゃない？

6. キミはひとりじゃない

6.1 面倒くさいことは、とりあえず生成AIに下処理してもらう

ありがたいことに現代では、生成AIさんがいる。さらにありがたいことに、（今のところは）無料でも結構な仕事をしてくれる。頼まない手はない。
ただ一つだけコツがある。

いきなり完成形 を頼まないこと。

これだけ。これまで説明してきた通り「意味の手がかりが少ないもの」「大きいもの」を、そのまま扱うのは、あんまり得意じゃない。
それで、意味の手がかりを増やして、大きいものを分割するのが構造化…という話は、カンの良いキミなら、なんとなくお察しだと思う。

なので、ここでも「分ける」「並べる」「名づける」「つなぐ」を早速使う。といっても、とても簡単だ。

6.2 このプロンプトを順番に渡せばいい

要するに、分けて、順序よく、頼めばいい。
一足飛びの大ジャンプでコケるなら、ホップ・ステップ・ジャンプの3段跳びをすればいい。ちゃんとゴールにたどり着ければ結果は同じだ。

まずだらだらっと思いつくままに書いた文章とか、あーしたいとかこーしたいとかを書き並べたものを用意する。そしたら、次のプロンプトで、順番に頼んでみる。

分けるプロンプト

この文章を、話題ごとに箇条書きへ分けてください。

並べるプロンプト

この箇条書きを、似ているもの同士が近くなるように並べ替えてください。

名づけるプロンプト

それぞれのまとまりに、短い見出しをつけてください。

つなぐプロンプト

まとまり同士の関係を、Mermaidの図にしてください。

6.3 行ったりきたりしてもいい

多分、紹介した（というほど大したもんじゃないが）プロンプトを実行すると、不意にひらめいたり気づいたりすることがあって、直したくなるかもしれない。

ためらうことはない。ひらめきや気付きを足して、直せばいい。

実際のところ、ボクも、そうしてる。

だいじょうぶ。やりなおしを何度たのんでも、生成AIさんは不機嫌になったりしない。
なんなら、ちょいちょい褒め言葉を挟んで、むしろボクらをいい気分にさせながら仕事に取り掛かってくれる。
空気は読めないけど、良い子なので。

そうこうしてるうちにコツが掴めてくれるし、頭の中もすっきりしてくる。
生成AIさんに易しい文章は、おニンゲンさんにも易しいんだ。

6.4 あれ、Markdownを書くって話はどこいった？

この章で紹介したプロンプトを試してるうちに、キミの文章はもう構造化されてる。
あとはちょっと「お作法」に寄せて、記号を足すだけでいい。
なんなら生成AIさんに「マークダウンして」って頼んでもいい。

実は、ここまでの過程を試してたら、最初の頃と比べて 「思ってたんと、なんか違う」　はかなり減ってると思う。

なので、出来上がったドキュメントにすっかり満足したら、別にMarkdownにしなくてもいい。…身も蓋もないけど。
でも、何度も使い回したいもの、誰かに渡したいもの、あとから育てていきたいものなら、Markdownにしておく価値はある。情報に「かたち」が残るからだ。

7. おめでとう、キミはこの長い記事から卒業だ！

ここまで実際に試してみたキミは、もう卒業だ。
ボクから教えることは何もない。

ここまでおつきあい頂いてありがとう。きっと、だいぶ疲れただろう。
実は書いてるボクも、ぐったり疲れた。
ほんの僅かでも、何かの役に立つことがあったら幸いだ。

…。
……。
………。

ところでさ、もしかしてだけど、この記事、生成AIさんにコピペして「要約して」なんて頼んでないよね？