LLM時代はテキスト形式でドキュメントを書く 2. ドキュメントを書く
利用ツールはGithub Copilot Coding Agentに決まりましたが、使い始める前に編集対象のファイルを作成する必要があります。
今回は、プログラムではなくドキュメントに対してGithub Copilot Coding Agentを利用するのですが、対応しているドキュメントはテキスト形式のみです。よってテキスト形式、具体的にはmarkdown記法で書きます。
Markdown記法とは?
Officeファイルを使わずとも、テキスト形式(txt)で太字や章立てを表現したい、というニーズから生まれたテキスト記載方法です。2004年頃はいろいろな記法が乱立していましたが(ウィキ記法、AsciiDoc)、2025年現在ではMarkdown記法が事実上の標準となっています。
どれくらい標準かというと、Microsoft Teamsでも使えますし、Windows 11のメモ帳でも使えるようになりました。
Markdown記法をまなぶ
「Markdown 記法」で検索すると、いくつかページが出てきます。
いろいろな記法があるし、特定の環境でしか使えない特別な記法もありそうで迷うと思います。
が、はっきり言うとMarkdown記法で、覚える記法は2つだけです。
覚えるべき2つの記法「章立て」と「リスト」
この2つだけを覚えておけばMarkdown記法で文章は書けます。私は普段からMarkdownで文章を書きますが、マジで自分で書く記法はこの2つが99%です(後述しますが、ツールに支援してもらって記載する記法はあります)。
章立て
# → H1(文章タイトル)
## → H2(章区切り)
### → H3(節区切り)
リスト
-
-
-
終わり。めちゃ簡単です。
例えば、Wordを使う時も、Wordの機能全部を使って文章書かないですよね？せいぜい、章立てや太字、必要に応じて箇条書きくらいじゃないですか？
WordじゃなくてGoogleドキュメントを使いなさい、と言われても、とりあえず文章を書き始める事はできますよね？
Markdownも覚える事はほとんどなく、今日から書き始められるものである、と思って下さい。
たまに使う「太字」「斜体」「ブロック」「引用」
その他、覚えておいてもいいかなレベルの記法です。太字くらいは使うかな。
太字
**太字にする文章**
斜体
*斜体にする文章*
ブロック
```powershell
Get-ChildItems
```
引用
> 引用する文章をここに書きます
> 引用する文章をここに書きます
> 引用する文章をここに書きます
よく使うけど自分で書くことはない「表(table)」「リンク」「画像貼り付け」
全て、Markdown記法で文章を書くときには必要ですが、自分で書くのが難しすぎるので後述する拡張機能やツールに任せちゃいます。リンクくらいは自分で書くこともあるけれど。
表(table)
| Head | Head | Head |
| ---- | ---- | ---- |
| Text | Text | Text |
| Text | Text | Text |
リンク
[リンクさせる文字列](リンクのURL)
画像貼り付け
注意：Markdown記法は万能ではない
Markdown記法はあくまでテキスト形式の簡易記法です。
- プレゼン資料としてはPowerPointにかなわず
- 表計算や表描写はExcelにかなわず
- 印刷前提の組版ではWordにかなわず
Word / Excel / PowerPoint / Markdownの比較表
| 観点 | Word（.docx） | Excel(.xlsx) | PowerPoint（.pptx） | Markdown(.md) |
|---|---|---|---|---|
| 差分/変更履歴 | △ 校閲履歴で対応 | × 厳しい | × 厳しい | ◎ Git管理で完璧 |
| AIとの相性 | △ Copilot | △ Copilot | △ Copilot | ◎ テキスト形式 |
| 文章構造 | ◎ スタイル/目次/脚注 | △ シート管理、独自表現 | ○ セクション管理 | ○ 見出し/リスト/コード/引用 |
| 表 | ○ 表OK | ◎ 表に連動したグラフ | ○ 表OK | △ Markdownのtable |
| 図 | △ 可能だが操作難 | ○ 図OK | ◎ 図形特化 | ○ Mermaid記法、PlantUML記法 |
| ビジュアル表現 | △ Officeの範囲内で実現 | △ Officeの範囲内で実現 | ◎ アニメーション/動画など | × 皆無 |
| 数式・計算 | △ 簡易式程度 | ◎ 関数/分析 | × なし | △ 基本なし(拡張利用で可) |
| レイアウト・印刷 | ◎ 正確 | △ 印刷範囲指定 | ◎ 正確 | △ ツール依存 |
| 共同編集 | ◎ 同時編集 | ◎ 同時編集 | ◎ 同時編集 | ○ Git＋PRで非同期 |
| 画像・添付管理 | ○ 文書内埋め込み可(位置合わせ難) | ◎ シート埋め込み | ◎ 画像/動画/図形の一体管理が簡単 | △ 相対パスで外部管理 |
特に気になる以下の3つです。対策も合わせて紹介します。
| 観点 | デメリット | 対策 |
|---|---|---|
| 表 | Markdown 記法で記載する必要があるが、自分で1から書くのは現実的ではない | Excelで表を作成して貼り付ける、AIに依頼して表を書いてもらう。 |
| 図 | テキスト形式なので、表現できない | mermaid記法を利用する。(AIに依頼前提) |
| 画像 | Markdown ファイルと別ファイルで管理する必要がある | Markdownエディタの拡張を利用して画像を貼り付ける、画像管理フォルダを決める |
イメージとしては、SIプロジェクトなどで基本設計書をWord形式で記載する面倒くささです。文章を書くのはいいですが、表を貼り付けるとなると横幅が決まっていてやりづらかったり、行列の入れ替えがしづらかったりします。表の大きさによっては、別ファイルのExcelを参照、としたりします。
構成図などの図解についても、Wordだけで表現するのは困難なのでPowerPointなどの別ファイルをマスターとすることが多いですよね。
画像についても、画像のバージョン管理ができないため、プロジェクトによってはWordで使用した画像を保管するフォルダと画像ファイルの命名ルールが決まっているものもあります。
覚えてほしいのは以下となります。
- 不便な点について対策はありますが、他のOfficeファイルよりも使い勝手は劣る
- 無理にMarkdownにこだわるのではなく、適材適所と考える
- ただし、AIの利用とMarkdown記法への慣れでカバー、どころかMarkdownの方が使い勝手がよくなる
mermaid記法とは
mermaid記法は、テキスト形式でフローチャートやレーン図を記載できる記法です。
Officeファイルであれば、図形を作ってコネクタでぽちぽち作業するところを、テキストベースで軽快に記載が可能となります。とはいえ、これらを1から書くのは大変なのでAIの力を借りて書いてもらいます。
図表をテキスト形式で記載する記法はこの他にPlantUMLなどがありますが、今回はmermaid記法のみを取り上げます。詳しくはまた後で説明しますので、今は名前だけ覚えておいてください。
Markdownのはじめかた
冒頭で「メモ帳でもMarkdown記法で書ける」と言いましたが、さすがにメモ帳でやり続けるのはしんどいので専用のエディタを用意します。専用、といってもみなさん利用されているであろうVisual Studio Code(以下、VSCode)なので問題ないと思います。
※ この他に、Obsidian、Typoraあたりがメジャーなエディタとなりますが、ここでは取り上げません。
VSCodeに加えて、VSCodeの拡張機能をセットアップする必要があるので、その手順を書きます。
セットアップ手順
1. VSCodeのインストール
Download Visual Studio Code - Mac, Linux, Windows
2. 拡張機能のインストール
VSCodeでmarkdownを書きやすくする、表や画像の弱点を解消するために拡張をインストールします。各目的と対応する拡張機能は以下の通りです。
| - | Markdown All in One | Excel to Markdown table | markdown table | table editor | Paste Image | Markdown Preview Mermaid Support |
|---|---|---|---|---|---|---|
| markdownファイルに目次をつけ、自動更新する | ○ | |||||
| markdown記法の入力支援を行う | ○ | |||||
| Excelで表を作成して、markdownファイルに貼り付ける | ○ | |||||
| markdownファイルに貼り付けた表を編集する | ○ | △ | ||||
| markdownファイルに画像を貼り付ける | ○ | |||||
| Mermaid記法のプレビューを行う | ○ | |||||
| 作成したmarkdownをPDFとしてエクスポートする | ○ |
これらの拡張の使い方は次項の習慣化ドリルで見ていきます。
で、このタイミングで後々利用するGithub Copilot、Github Copilot Chatの拡張機能もインストールしておきます。
3. gitのインストール
gitはテキストファイル用のバージョン管理ソフトウェアです。詳しい説明は検索すれば出てくるので割愛し、ここではダウンロード方法だけを書きます。
1. ダウンロード
Git - Downloading Packageからダウンロードします。Click here to downloadをクリックすればよいです。
2. インストール
デフォルト設定で問題ありませんが、Choosing the default editorだけvscodeを選択してください。
Markdown習慣化ドリル
今から一番大事な事を言います。このドリルを1年間毎日続ける事。じゃないと、この研修の意味がなくなります。1年間じゃなくてもいいけど、1ヵ月は続けてください。もちろんTeamsの投稿など、書けるところはMarkdown記法で書くことが大事です。
Markdown記法でスムーズに書くためには、Markdown記法の暗記やキーボードショートカットの利用が必要です。これを頭で考えるよりも先に手が動く状態にする、小学生がやる漢字の書き取りや公文式の計算練習のような練習が大事です。
特に20代の方は一生使えるスキルを手になじませるチャンスだと思ってください。現に私はテキストエディタを利用した正規表現置換を業務上使いまくっていた時期があり、今でも正規表現を何も考えずに書くことができます。簡単なデータ分析などでデータ整形をする際に、脳のリソースを使わずに作業ができるので大変楽です。
Markdown記法は少なくともあと10年、もしかすると30年・50年は使える記法です。実際、正規表現は1970年代に登場して50年経った今では完全な標準となってます。この機会に手になじませ、普通のものとして身に付けられればOKです。
それでは次エントリで具体的なドリルの内容を書いていきます。
Discussion