呪いのドキュメント（こわくないよ）

おはようございます。こんにちは。こんばんは。ふぇにっくちゅん です。

みなさんは、普段文章をどこに置いているでしょうか？
手元のパソコン、社内の共有ファイルシステム、Wiki サーバ、ブログサーバ、色々とあると思います。
適切な場所に、文章があることは良いことです。

では、これらに配置された文章を引っ越しすると仮定します。
場合によりますが、面倒に感じないでしょうか。
たとえば、Wiki のページを別のブログサーバに引っ越すというケースでは面倒です。

また、文章を引っ越しする際のアクセス権も意識しなければなりません。
たとえば、ファイルシステムから GitHub Enterprise へ引っ越しする際に困ることがあります。
ディレクトリ単位のアクセスコントロールから、リポジトリ単位のコントロールに変わるからです。

実は、知らない間に、文書がシステムの機能に依存しているのです。
これが、文章に取り憑くシステムの呪いです。
本記事は、この文章（ドキュメント）に取り憑く呪いについて取り上げます。

残念ながら、この呪いを無くすことはできません。
しかし、できるだけこの呪いを軽減させることはできます。
以降では、この呪いと軽減策を紹介します。

文章が呪われている

まず、文章に取り憑く呪いを考えてみます。

1. 手段
2. 書き方（お作法、記法）
3. 置き場所
4. 見せ方

大きく、この4つの呪いが考えられます。
呪いというと、わかりにくいかもしれません。
「呪い」を言い換えると、文章を書いて共有するまでの工程における「選択肢」です。

たとえば、書く手段は、鉛筆と紙、パソコン上のエディタ、これらの選択肢です。
書き方で言えば、箇条書き、〇〇フォーマット、記法、などが選択できます。
置き場所や見せ方も、同じように選択肢があります。

この選択肢が、文章の引っ越しという、あるタイミングで呪いに変わります。
たとえば、同じ Markdown に方言があるように、書いたものがそのまま使えない場合があります。
記法やフォーマットが異なれば「文章を引っ越しする」ということが難しくなってしまいます。
つまり、引っ越し元と先で、上述した選択肢の摩擦が、呪いの度合いを決めることになります。

ドキュメントの価値が選択肢を決める

摩擦を減らすためには、ドキュメントの生存期間を考えると良い選択がしやすくなります。
この生存期間をイメージするために、2つほど例を出します。

まず、書いた文章が自分のためのメモだと仮定します。
つまり、不要になったら、メモを捨てることができるため、ドキュメントが作成されてゴミ箱に入るまでの期間は短いです。
この場合は、好きなエディタで、好きな文章の書き方、見せ方（閲覧権限）を自分だけにできる場所を選べば良いです。
要するに文書としては、雑に扱うことができ、短期的な価値しかないということです。

次に、公開する文章を書くと仮定します。
つまり、ドキュメントは長く公開され続けるため、生存期間は先程よりも長いです。
また、公開する文書であれば、長期的な価値をだせるようにするのが一般的です。

この場合は、置き場所が重要となります。
閲覧できる or 閲覧しやすいところに置くと、公開文章として目的を達成できるからです。
選択肢の観点でいうと、どこにおいても良いというわけではないため、置き場所の選択肢は少なくなります。
公開する文章の場合、書く手段も、使うシステムによっては選択肢が少ない場合があります。
ブログなどのシステムによっては、ブラウザ上で入力を強いられ、好きなエディタは選びにくいです。

これらの例で分かる通り、すぐ捨ててしまうようなドキュメントは選択肢が多く、大切なドキュメントは選択肢が少ない、ということです。
選択肢が少ないほど、摩擦が発生しやすい状況となります。
逆に選択肢が多いほど、柔軟に対応できるため、摩擦が発生しにくい状況を作ることもできます。
つまり、ドキュメントの価値が短期的であれば、呪いが弱く、長期的であれば、呪いが強くなります。

では、みなさんが普段書く文章はどちらが多いでしょうか？
システムのマニュアル、教育資料、議事録、大切なものが多いと思います。
つまり、価値の高い文章を作成していることが多いわけです。
その分、選択肢も少なくなっています。

これで、仕事として作成している文章は、呪われやい状況であることがわかると思います。

摩擦を減らすための工夫

選択肢が少ない中で、摩擦が発生しにくい状況は作れないものでしょうか？
これはなかかな難しいです。
冒頭に伝えたとおり、呪いはなくなりません。
つまり、摩擦が発生すると、どうしても苦労が発生してしまいます。

しかし、この摩擦に影響されにくい状況を作ることはできます。
仮にドキュメントの管理システムが、ドキュメントの生存期間（価値が出せる期間）よりも長く使うことができれば摩擦は発生しません。
要するに、ドキュメントを捨ててしまえば、管理するものがなくなったシステムも捨てる事ができるからです。
このような状況は稀ですが、摩擦が発生しないという意味では、良い例です。

では、よくありそうな状況を考えてみます。
ドキュメントの管理システムは、複数の人や複数の組織が共有して使っている場合が多いです。
この場合、適宜新しいドキュメントが追加され、管理しているドキュメント群として生存期間が伸び続けます。
つまり、システムのほうが先に古くなってしまう可能性があります。

この状況では、将来的にドキュメントの管理システムを、全く別のシステムに変更することがあることを想定しておくことが大切です。
実際に引っ越しをするときに、システムの仕様や機能などに依存したドキュメントがあると、呪いの対処を行うというおまけが付いてきます。

では、引っ越しがあることが前提として、どのようにシステムを選んでいけばよいでしょうか？
選択肢が少ない中でも、より選択肢が広い機能を選べばよいということです。
それ以外にも、ドキュメントを管理するシステムを誰が利用するかを想定することも大切です。
これが、摩擦を減らすための工夫になります。

では、cats_dogs はどうでしょうか？

cats_dogs の選択肢

先程の呪い（選択肢）を考えてみます。

1. 手段
   • 好きなエディタ
2. 書き方（お作法、記法）
   • Markdown
3. 置き場所
   • Web サーバ
4. 見せ方
   • 認証・認可の機能

これが、エンジニアのために呪いを減らしてくれます。
もう少し詳細な cats_dogs の選択肢について紹介します。

cats_dogs の選択理由

まず、書く手段についてです。
エンジニアは、電子データを扱うことが大半であるため、好きなエディタが選べるといいです。
VSCode や Vim、Emacs などエンジニアは自分の好きなエディタを選びたがります。
テキストデータを扱うシステムである以上、書く手段は多いです。

次に、書き方です。
Markdown は、エンジニアとして良く使う記法です。
書き方が Markdown 記法に依存しているのは如何なものか？と思うかもしれません。
しかし、GitHub を運営している組織が巨大であるため、 Markdown で文章を記述しなくなることは、まだ先になると思います。
つまり、選択肢が少ない代わりに、書き方の寿命が長い（だろう）ものを選択しています。

次に、置き場所です。
社内で作成するドキュメントの価値が高いという前提は既に説明しました。
つまり、価値を高めるためには、自分だけでなく他の人に見せられる状況にする必要があります。
閲覧に、特別なツールなどが必要であると、価値を高める邪魔をしてしまうため、誰もが使うブラウザを選択しています。
これは、ブラウザの選択肢しかありませんが、選択すら必要がないほど、ブラウザが一般的なツールとなっているためです。 そのため、置き場所は Web サーバとなります。

最後に、見せ方です。
cats_dogs は Markdown ファイルの部分的な文章だけを、見せる or 見せない のコントロールができます。
これだけでは、見せ方の選択肢が少ないですが、ngx_auth_mod を組み合わせて使うことで、選択肢が広がります。
ngx_auth_mod であれば、簡単に URL のパス単位で認可設定できるため、適切な人に適切な内容を、選択して見せることができます。

さいごに

ここまで読んで、呪いが少ないと感じる方と、そうでない方がいると思います。
実は、呪いを少なくするには、前提が大切です。
この前提とは、ドキュメントを管理するシステムを誰が利用するか？ということです。
たとえば、Markdown で頻繁に文章を書き、GitHub も利用する機会が多ければ、cats_dogs を利用することで、呪いが少なく感じると思います。

つまり、呪いはなくなりません。
呪いを強く感じるか、弱く感じるかは、前提の違いであって、感度の問題だからです。
また、時代の流れによっては、急に呪いを強く感じる場合もあります。
たとえば、Markdown 記法以外が流行ったときです。
このときには、呪いを噛み締めて、ドキュメントを引っ越しましょう。