ドキュメントを書くときの視点

POPFile の本家のフォーラム に、最近、「Documentation?」という投稿があった。質問の趣旨は、「マグネット」「設定」「セキュリティ」「詳細設定」のそれぞれのタブについての説明が書かれたドキュメントはどこにあるのか、というものだった。それを見たときに、なぜかちょっとした違和感を覚えた。
確かに、POPFileDocumentationProject にはそれぞれのタブについて説明したページがない。これは、オリジナルのマニュアル についても同様だ。これまで、このことが不思議だと思ったことはなかったので、上記のメッセージを見て、「あれ？」と思ったのだ。
しかし、タブごとの説明がないことによって困ったことがあったかと言うと、（あくまで個人的に、だが）特になかったのだ。今でも、「セキュリティ」タブにある「リモートサーバー」というオプションが何をするものか、なんてことはわからなかったりするけれど、それはきっと私の使い方では「知らなくてもよいこと」なのだ。利用者が知りたいのは、「こんなことをしたいのだけど、どうすれば？」ということであって、それは、FAQ や HowTos といったページにまとまっているのだ。これらのページにはかなり膨大な情報が掲載されていて、ほとんどの疑問はここで解決してしまう。
そう考えると、タブごとの説明というのは、実際にはいらないのではないかと思えてくる。上に書いた、「セキュリティ」タブの「リモートサーバー」というオプションを見て、「これは何をするものだろう？」と考える人がいるかもしれないが、そう思う人はあまりいないのではないかと思うのだ（それが調べたければ、例えば「SPA/AUTH」で検索すれば、Is POPFile compatible with Secure Password Authentication/AUTH? というページが見つかり、疑問は解決する）。逆に、SPA/AUTH を使いたい、という人が、FAQ を見て、「ああ、ここで設定するのか」とわかるという流れが自然なのではないかな。

と、こんなことを書いておいてなんなのだけど、先日書いた、IconParty マニュアル を見ると、まったく逆になっている。まず、ウィンドウの説明から始まり、ツール、メニュー、といった具合で、それぞれの機能から説明するというアプローチをとっている。利用者が、例えば、ある色を別の色に置き換えたいと思ったとき、それをどうすればいいのか、というのはこれを見ただけではわからない（それができるかどうかさえも）。私は、その機能があることを知っていて（当然だけど）、どうすればいいのかもわかるから、それがカラーパレットに書かれていることもわかるのだが、それを知らなければ探しようがないのだ。

こうして２つのドキュメントを比べてみると、それらがどのような視点で書かれたかがよくわかるような気がする。POPFile のドキュメントは利用者の視点で書かれていて、IconParty のドキュメントは制作者の視点で書かれているのだ。制作者の視点から見ると、それぞれの機能（なりオブジェクトなり）を順に説明したくなる。その方がなにかと楽だし、すべての機能を説明するのに好都合だから。だけど、利用者から見ると、そんなマニュアルが見やすいだろうか。自分のしたいことがどこに書いてあるのかがわからないマニュアルなんて、役に立つだろうか。幸い、Wiki ベースに作り直したので検索ができることが救いだが、使いやすいマニュアルになっていないことは確かだ。反省。
ということで、これまで質問いただいた項目や、要望があって追加した項目などについて、FAQ、HowTos といったコーナーを作っていく予定。POPFile のプロジェクトは、ほんとにいろいろなことを教えてくれる。