Markdown Documentationのススメ
Tadashi Aikawa
2025/08/13 Minerva Lightning Talks

Tadashi Aikawa

Productivity Creator since 2010
OS
Mac / Windows(AI)
ターミナル
Ghostty
言語
TypeScript >> Python = Go > Lua > Rust
エディタ
Neovim / Obsidian
デバイス
EIZO / HHKB Studio
サイト
Minerva GitHub Bluesky
好き
創作活動・温泉・甘味・動物(ぬいぐるみ含む)
苦手
お酒・車・勉強
楽しい仕事
個人やチームの生産性を上げて成果に繋げる

ドキュメンテーション経歴

年(大体) ツール 言語 ホスティング
2010～2012 PukiWiki wiki 〃
2012～2013 Google Site 独自 〃
2013～2015 Sphinx reStructuredText Read the Docs
2013～2017 Wordpress (ブログ) 独自 自前サーバー
2015～2019 Markdown Markdown Dropbox
2017～2021 Hugo (ブログ) Markdown Netlify -> Vercel
2019～2021 MkDocs Markdown Netlify -> Vercel
2021〜2025 Obsidian Markdown + wiki Obsidian Publish
会社では最近までobsidian.nvimを使っていました

Obsidianと私

Agenda

  1. なぜMarkdownでドキュメントを管理するのか？
  2. Markdownドキュメントを楽に管理するには？
  3. Markdownドキュメントを共有するには？
  4. まとめ

Chapter

01

  1. なぜMarkdownでドキュメントを管理するのか？
  2. Markdownドキュメントを楽に管理するには？
  3. Markdownドキュメントを共有するには？
  4. まとめ

3つの理由

  1. 個人のメモ/タスク管理に向いている
  2. プロダクトドキュメントの管理に向いている
  3. AIとの相性が良い

1. 個人のメモ/タスク管理に向いている

  • ローカル管理でサクサク
  • 情報の関連付けに強い
  • 検索・加工しやすい (個人差あり)

2. プロダクトドキュメントの管理に向いている

  • 情報の関連付けに強い
  • Gitでバージョン管理できる
    • 変更履歴を追いやすい
    • ドキュメントもブランチで編集できる
    • PRレビューできる

3. AIとの相性が良い

  • ローカルファイルなので読み込みが速く、入力情報量も多い
    • SaaS MCPだと検索APIの性能がボトルネックになりがち
  • テキストなのでAIとコミュニケーションしやすい
    • Jiraのようなことは大体できる
  • プロダクトコードの仕様と実装をセットで共有できる
    • プロンプトで仕様や経緯の説明をしなくても話が進む

ただMarkdownにはこんな意見も...

  • NotionやConfluenceなどと比べて見にくい
  • 整合性を担保しながら編集するのが辛い
    • リンク先に変更・削除があったときの対応など
### 3. Grep

This feature requires [ripgrep](https://github.com/BurntSushi/ripgrep) and set the executable command to "Ripgrep command" option.

![Demo](https://raw.githubusercontent.com/tadashi-aikawa/obsidian-another-quick-switcher/master/demo/grep.gif)

It sorts results by modified time descending.

#### Additional hotkeys


| Command | Description | Default Hotkey |
|---------|-------------|----------------|
| Search | Execute search | `TAB` |
| Preview | Preview selected file | `Ctrl+,` |
| Toggle input focus | Switch focus between search query and path input | _(customizable)_ |
| Clear input | Clear the search query input | _(customizable)_ |
| Clear path | Clear the path input | _(customizable)_ |
| Set ./ to path | Set current directory to path input | _(customizable)_ |

Chapter

02

  1. なぜMarkdownでドキュメントを管理するのか？
  2. Markdownドキュメントを楽に管理するには？
  3. Markdownドキュメントを共有するには？
  4. まとめ

適切なツールなしでドキュメントを書くのは

IDEなしでコーディングするようなもの

Markdownドキュメンテーションのためのツール構成例

VSCode + Foam
Neovim + obsidian.nvim
Obsidian

Obsidianとは ローカルでMarkdownの知識ベース(PKM)を管理するアプリケーション

center

Obsidianのオススメポイント

  • 圧倒的な速さ
    • 12065ファイルで起動速度0.5秒くらい
    • プラグインを入れると遅くなるケースあり
  • 見た目の美しさ
  • カスタマイズ性の高さ
    • 2500以上のプラグイン
    • TypeScript/JavaScriptで自由自在
    • CSSで自分好みの見た目に

IDEのように快適な操作

操作 利用するプラグイン 備考
定義ジャンプ なし(標準)
リネーム なし(標準)
リンクのオートコンプリート Various Complements 標準でも可
ファイル検索 Another Quick Switcher 標準でも可
呼出履歴 Another Quick Switcher 標準でも可
Git操作 Obsidian Git
Vimモード なし(標準)

Wikiリンクのメリット

  • 文字数が少ない
    • Markdownリンク: [Obsidian](./Obsidian.md)
    • Wikiリンク: [[Obsidian]]
  • 場所に依存しない
    • Markdownリンク: [Markdown](./glossaries/languages/Markdown.md)
    • Wikiリンク: [[Markdown]]
  • 自然に文章が書ける/読める
    • Markdownリンク: [Obsidian](./Obsidian.md)は[Markdown](./languages/Markdown.md)が書きやすい
    • Wikiリンク: [[Obsidian]]は[[Markdown]]が書きやすい

Chapter

03

  1. なぜMarkdownでドキュメントを管理するのか？
  2. Markdownドキュメントを楽に管理するには？
  3. Markdownドキュメントを共有するには？
  4. まとめ

MkDocsを使おう

Mkdocsとは Python製のSSG。Markdownベースのドキュメントをデプロイできる。

Material for MkDocs

Obsidianとの互換性を保つ

利用例

Chapter

04

  1. なぜMarkdownでドキュメントを管理するのか？
  2. Markdownドキュメントを楽に管理するには？
  3. Markdownドキュメントを共有するには？
  4. まとめ

まとめ

Markdownドキュメントは

  • 『PKM』や『個人タスク管理』、『プロダクトドキュメント』と相性がいい
  • Obsidianを使いこなすと快適に管理できる
  • MkDocsでデプロイすると、他の人と共有できる

おまけ

ドキュメントを書き始める前に考えるべきことは？

ノートの作成場所をできるだけ 単一ディレクトリ 配下にしたほうがいい。

  • 同名ノート( = 同名用語)の存在に気づける
  • ドキュメンテーションビルダーでトラブルが発生しにくい
  • エディタでトラブルが発生しにくい

Markdownドキュメンテーションが向かないものは？

以下の条件を満たすようなものはやめたほうがいいかも。

  • 色々なPJから予期せず参照されることが多い
  • Markdownを書けない人が編集する機会が多い
  • プロダクトと関連性が弱い (PJ定例など)
  • リアルタイムで『編集 & 共有』が必要

オススメのObsidianプラグイン (主観)

プラグイン名 用途
🦉 Various Complements オートコンプリート
🦉 Another Quick Switcher Vault内のファイル確認・移動
Vimrc Support Plugin vimrcサポート
Periodic Notes Daily Note / Weekly Report
🦉 Silhouette タスク管理 (非公式)
🦉 Carnelian army knife (非公式) (今は自分専用)

世間で人気そうなObsidianプラグイン

プラグイン名 用途
Omni Search Vault内検索
Obsidian Tasks タスク管理
Kanban カンバン
Templater JavaScriptで即席処理
Dataview Confluenceのデータベース機能っぽい
※ Templaterについて
Obsidian 1.9でBasesという同様のコアプラグインが追加されるので待ったほうがいいかも

仕事だったら『所属』『代表プロダクト』『入社年』などを入れる