あなたのドキュメント泣いてませんか？

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

皆さんは普段どのような文章（ドキュメント）を書いていますか？
ふぇにっくちゅんは、調査した結果や分析の結果をまとめる、ブログを書くなどをしています。
他にも、システムのマニュアル、自分用のメモ、議事録など文書を書くシーンはあると思います。

その上で、なぜ文書を書くのか？について、考えたことはあるでしょうか？
それはすごく単純で、人に情報を伝える手段として、文書を書いているのです。
もちろん、手段であるので、音（Podcast、オンライン会議ツールなど）、映像（Youtubeなどの動画コンテンツサイト）などで伝える方法もあります。
これらは、どれが一番良いということはないですが、伝える相手や内容に合わせていけば良いです。

伝えるという行為は、コミュニケーションを目的としている場合が多いです。
コミュニケーションを取りたい相手によって、普段の手段とは異なる手段を選択することがあると思います。
要するに、伝える相手を選ぶ、その上で手段はどれが良いか、を無意識に選んでいるのです。
手段の選択もそうですが、適切な相手に伝えることも重要なポイントの一つです。

伝える相手は人であるため、多種多様です。
つまり、それに合わせて、文章を伝える手段も選択肢が多いと嬉しいわけです。
適切な相手、適切な手段を選べた上で、文章を伝えることができれば理想です。
以降では、一般的な文書を伝える手段と併せて、この理想を補助する cats_dogs の機能について説明します。

文書を伝えるツールの特性

現代では、紙に文書を書くよりも電子データとして文書を書くことが多くなりました。
文書を伝える手段は様々で、本記事のようにブログ、SNS、メール、チャットなどがあります。
ツールによっては、文字数制限やインタラクティブな操作により、会話に近い状況を生み出せるものもあります。
では、これらの文書を伝えるツールの特性を考えてみます。

ツールの特性1

ツールの特性である、文章の量とやり取りのスピードを比較します。

• 文書の量（多い順）

  1. ブログ
  2. メール
  3. チャット、SNS

• 文書のやり取りのスピード（早い順）

  1. チャット
  2. SNS
  3. メール
  4. ブログ（コメント欄）

やり取りのスピードは、文章量によって遅くなる側面もありますが、一般的には、ツールの特性によるところが大きいです。
たとえば、チャットは会話を文字で行うツールなので、やり取りすることが前提になっています。
そのため、やり取りを前提であれば、利用者の文書のやり取りは活発で、スピードも早いはずです。

一方で、ブログは一方向に伝える手段という認識が一般的で、やり取りを前提にしているツールではありません。
これが、上記に列挙したツールの大きな違いになります。
現に、ブログの記事に対してやり取りを行う場合には、SNSやチャット、メールに切り替えて会話することが多いと思います。

また、ブログは文章量が多くなる傾向があります。
そのため、詳細なことを伝えたいときには便利です。

cats_dogs は、ブラウザで文書を閲覧できる Web アプリケーションであるため、ブログと同じ特性を持っています。

ツールの特性2

つぎに、やり取りする対象範囲を考えてみます。

• 文章のやり取りの範囲（広い順）
  1. ブログ
  2. SNS
  3. メール、チャット

ブログは、ネットワークとしての到達性があれば、基本的には誰でも文章を読むこと（伝えること）ができます。
もちろん、社内のイントラネットにブログサイトがあれば、社内だけに絞ることができます。
他にも、以前公開した ngx_auth_mod などで、ブログサイトの URL にアクセス制限をかけることも可能です。

一方で、メールやチャットは、予め知っている相手に文書を伝えることができます。
そのため、小さい範囲でやり取りが可能です。
SNS はブログのように広い範囲で文章を伝えられますし、場合によっては限定的な範囲にすることもできます。

文書のやり取りの柔軟性は、SNS が高そうです。
しかし、SNS は長文を扱うことには不向きです。
つまり、長文を扱うことが自然なブログでも、もう少し柔軟に文書を伝えられると、手段の幅が広がりそうです。

あなただけの Markdown

では、長文を伝える対象の範囲を柔軟にするということはどういうことでしょうか。
実は、皆さんの身近なシステムやサービスにも組み込まれている機能です。

最近のシステムでは、アカウントを登録してログインすることが多いと思います。
ログインすると、ログインした人専用のページが表示されます。
つまり、ページの見栄えは誰でも同じですが、書かれている内容がログインした人に合わせて表示されます。
これが、長文を柔軟に伝える手段です。

文章を作成する側としては、まったく異なる内容を表示するには、別のドキュメントを作成すれば良いです。
しかし、ある程度の文章は同じで、内容が微妙に違う文章を作成するときには、別のドキュメントとして分けることが手間に感じてしまいます。
この手間を省いてしまうと、読み手に合わせて文章を作成することが難しくなります。
つまり、伝えなくても or 読まなくても良い文章が、一つのドキュメントの中で混在しやくなってしまいます。

ここで、cats_dogs の出番です。
cats_dogs は、 Markdown をブラウザで閲覧できる機能だけではありません。
文書を読む人に合わせて表示内容を動的に変更してくれる機能を備えています。
この機能は「GitHub から Markdown だけ切除してみた」で紹介した機能です。

この機能を使うことで、もう少し柔軟な文章の見せ方ができるようになります。
例えば、cats_dogs について説明する文章を書くケースを考えてみます。
このときに伝える相手は、管理者と開発者、一般ユーザであるとします。

また、書き手と読み手は以下のようなことを考えている例です。

• 書き手
  • タイトルの「cats_dogs のシステムについて」ということを書きたいと思っている
• 読み手
  • 自分に関係ないことは読みたくないと思っている

# cats_dogs のシステムについて

cats_dogs は Markdown で記述されたドキュメントをブラウザで閲覧できるアプリです。

{{if in_group "admin" -}}

## cats_dogs の運用について

cats_dogs のシステムを運用していくための内容を以下に示します。  
...

{{- end}}

{{if in_group "developer" -}}

## cats_dogs の開発について

cats_dogs の開発資料は、以下のリンクから入手できます。  
...

{{- end}}

{{if in_group "user" -}}

## cats_dogs の使い方について

cats_dogs の使い方は、... です。

{{- end}}

この機能を使用すれば、読み手に必要な情報を提示するだけでなく、書き手のドキュメントが一つに収まりやすくなるメリットがあります。
この機能がなければ、同じ題材に対して 管理者・開発者・一般ユーザ 用にそれぞれドキュメントを作成しなければなりません。
もちろん、ドキュメントを分割して管理したほうが良い場面もあります。
しかし、より柔軟な文書作成が cats_dogs で可能になったことは間違いありません。

文書を伝える工夫

ふぇにっくちゅんは、文章を書くプロではないため、凡人でも文書を相手に伝える工夫が必要です。
先程紹介した cats_dogs の機能は、見せたくない内容を “隠す” 機能と言うことができます。
言い換えると、見せたい内容だけに “絞る” 機能と言うこともできます。
同じ機能でも、視点を変えると雰囲気が変わります。

文書の内容が秘密であれば、前者の “隠す” 機能として使えば良いです。
一方で、相手に伝えるべき内容を、シンプルに伝えるのであれば “絞る” する機能として使えば良いです。
文章を伝えるという意味では、後者のほうが重要です。

実際に文書を読むときに、必要がない情報が目に止まって、文書を読む際のじゃまになるケースがあります。
これでは、せっかく書いた文章が泣いてしまいます。
ページを分けて対処する他にも、同じドキュメントの中で、見せる or 見せないのコントロールができると嬉しいことがあります。
この機能があることで、文章が相手に伝わりやすくなります。

皆さんも、見せたくないという “隠す” だけではなく、人に伝えるべき内容をシンプルにする “絞る” 機能としても使ってみてください。