[[📒Productivityを上げるために大切な100のこと]] No78. 🥈
----
ドキュメントを書く必要が出たら選択肢がいくつかあることだろう。私の場合は以下のような選択肢がある。
| コンテンツ作成ツール | 公開方法 | 備考 |
| -------------------- | -------------------- | ----------------- |
| [[Obsidian]] | [[Obsidian Publish]] | プライベート |
| [[Obsidian]] | [[MkDocs]] | プライベート |
| [[IDE]] | [[MkDocs]] | 仕事 |
| [[IDE]] | [[docsify]] | 仕事 |
| [[IDE]] | README | 仕事/プライベート |
| [[Confluence]] | [[Confluence]] | 仕事 |
どのソリューションを使うにしても私が気を付けているのは、==ディレクトリやファイルの構造に依存しないリンク機能を使ってドキュメントを書くようにしている==ということだ。
## 構造に依存するリンク
[[#構造に依存するリンク]]とは、==ディレクトリやファイルの構造に変化があったとき、無効になってしまうリンク==のことだ。たとえば、以下のようなファイル構造があったとする。
```ls
.
├── dir1
│ └── file1.md
└── index.md
```
`index.md`に記載された以下が[[#構造に依存するリンク]]だ。
```txt:index.md
[file1](./dir1/file1.md)が構造に依存するリンク
```
`index.md`から見て、`./dir1/file1.md`は存在するのでリンクとなる。しかし、ディレクトリツリー構造に変更があり、以下のように変わったとする。
```ls
.
├── index.md
└── resources
└── file1.md
```
すると先ほどのリンクは無効となる。以下のように修正をしなければ有効にならない。
```txt:index.md
[file1](./resources/file1.md)が構造に依存するリンク
```
## 構造に依存するリンクのデメリット
もうお分かりだろう。[[#構造に依存するリンク]]の欠点は以下のようになる。
- **ディレクトリやファイルの移動**による影響を受ける可能性がある
- **ディレクトリやファイルの名称変更**による影響を受ける可能性がある
- [[Markdown]]ファイル内のリンクでパスの指定を間違えやすい
既存の項目にリンクしたいだけにもかかわらず様々なことに気を使わなければならないのだ。面倒なため、段々とリンクを使わなくなる。リンクを使わなくなることのリスクは以下の通りだ。
- 用語の表記ゆれが発生しやすい
- 閲覧者がその用語の意味を知らなかったときに補足説明を提供しにくい
リンクを使い続ければ、上記のリスクは大幅に削減できる。
## 構造に依存しないリンク
[[#構造に依存しないリンク]]とは、==ディレクトリやファイルの構造に変化があったとしても、無効にならないリンク==のことだ。先ほどと同様の構成をイメージしてほしい。
```ls
.
├── dir1
│ └── file1.md
└── index.md
```
今度は`index.md`に[[#構造に依存しないリンク]][^1]を記載してみる。
```txt:index.md
[[file1]]が構造に依存しないリンク
```
`index.md`から見て、`file1`に相当するファイルは`./dir1/file1.md`は存在する。しかし、ツリー構造は関与せず、==プロジェクト全体で唯一存在するはずのfile1.mdへリンクする==という挙動をとるのだ。そのため、以下のように構造が変わったときもリンクは`[[file1]]`のままである。
```ls
.
├── index.md
└── resources
└── file1.md
```
## 構造に依存しないリンクのメリット
それでは、構造に依存しないリンクのメリットを挙げてみよう。先ほどの逆になるので以下の通りだ。
- **ディレクトリやファイルの移動**による影響を受けない
- **ディレクトリやファイルの名称変更**による影響を受けない
- [[Markdown]]ファイル内のリンクを指定しやすい
- 名称衝突を回避できる
人間が読むうえで必要な情報はファイルまたはリンクの名前であり、それに至るpathはノイズになることが多い..と考えれば理にかなっているだろう。
また、これは考え方によってデメリットにもなり得るが、==[[#構造に依存しないリンク]]を使う場合、ディレクトリパスが異なっていても、同一名称を複数定義することはできない。==これをどう捉えるかはかなり重要なポイントだ。同一の用語を別ディレクトリで定義してしまうと冗長になるが、コンテキストをディレクトリで表現する場合、別ディレクトリの同一用語は別の意味を持つからだ。
なお、私は最近 [[💿MIN-0012 すべてをNoteディレクトリ直下に配置する]]ように戦略を変更した。別ディレクトリの同一ファイル名(用語)が意図的かそうでないかの判別が困難なため、仕組みでそれを防ぐようにした。
<div class="link-card">
<div class="link-card-header">
<img src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png" class="link-card-site-icon"/>
<span class="link-card-site-name">minerva.mamansoft.net</span>
</div>
<div class="link-card-body">
<div class="link-card-content">
<div>
<p class="link-card-title">💿MIN-0012 すべてをNoteディレクトリ直下に配置する</p>
</div>
<div class="link-card-description">
Obsidian Publishの見栄えは悪くなる懸念はあるが、それを上回るメリットがありそう。なによりMinervaは自分のためである。
</div>
</div>
<img src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/Notes/attachments/minerva-image.webp" class="link-card-image" />
</div>
<a
class="internal-link"
data-href="💿MIN-0012 すべてをNoteディレクトリ直下に配置する"
></a>
</div>
それらをどう扱うかは[[Wikipedia]]の設計が参考になるだろう。[[曖昧さ回避]]の一読をオススメする。
<div class="link-card">
<div class="link-card-header">
<img src="https://ja.wikipedia.org/static/favicon/wikipedia.ico" class="link-card-site-icon"/>
<span class="link-card-site-name">ja.wikipedia.org</span>
</div>
<div class="link-card-body">
<div class="link-card-content">
<div>
<p class="link-card-title">Wikipedia:曖昧さ回避 - Wikipedia</p>
</div>
<div class="link-card-description">
ウィキペディアにおいて、内容が異なる主題なのに適切な記事名が同じになってしまうときに、それらを判別しやすくすることを曖昧さ回避（あいまいさかいひ、Disambiguation）と呼びます。
</div>
</div>
</div>
<a href="https://ja.wikipedia.org/wiki/Wikipedia:%E6%9B%96%E6%98%A7%E3%81%95%E5%9B%9E%E9%81%BF"></a>
</div>
## 構造に依存しないリンクでドキュメントを書く手段
[[Markdown]]とは異なり、[[wikiリンク]]のような[[#構造に依存しないリンク]]はすべてのツールで対応しているわけではない。いくつか選択肢はあるが私のオススメは以下の通りだ。
- コンテンツ作成ツール
- [[Obsidian]]
- 公開方法
- [[Obsidian Publish]]
- [[MkDocs]] with [[obsidian-publish-mkdocs]]
- [[docsify]] with [[docsify-wikilink]]
[^1]: この例では [[wikiリンク]] を使っているが、[[Markdown]]の仕様ではないためエディタ側でプラグインなどが必要になることが多い