臨界点を超えた先のコミュニケーションモデルオープンソースソフトウェアの育て方(2/3 ページ)

» 2009年10月07日 08時00分 公開
[Karl Fogel, ]

アーカイブを目につきやすくする方法

 通常は、オープンソースプロジェクトにおけるあらゆるやり取りの内容は(IRCでの会話は例外として)保存されます。そのアーカイブは、一般に公開された検索可能な場所に配置され、常に参照できるようになります。すなわち、何らかの情報が特定の場所に保存されたら、それは常に同じ場所に存在する必要があるということです。

 できるだけこれらのアーカイブを活用し、その存在を広めましょう。たとえ分かりきった内容の質問に答える場合でも、その答えを含むアーカイブがありそうならそれを探して場所を示した方がいいでしょう。あなた自身が常にそのようにするよう心がけていると、「アーカイブがそこにある」「アーカイブを検索すれば答えが得られる」ということに気づいてくれる人も現れるでしょう。

 また、同じ内容をあらためて書き直すのではなくアーカイブを参照させることで、「同じ情報を重複させない」という指針を守ることができます。同じ回答をわざわざ複数の場所に分散させる必要なんてありますか? このような重複をできるだけ減らすように心がければ、ある回答に以前にたどり着いた人が、それを再び見つけ出すことも簡単になるでしょう。参照をうまく利用することは、検索結果全般にもよい影響を与えます。というのも、インターネットのサーチエンジンはほかの場所から多く参照されているリソースを重視するからです。

 しかし、場合によっては情報を多重化してもいいこともあります。例えば、あなた以外の人が投稿した次のようなメッセージがアーカイブ内にすでにあるとしましょう。

恐らくScanleyのインデックスが狂い始めているのでしょう。

復旧させるには次の手順を実行してください。

  1. Scanleyサーバを停止する
  2. Scanleyに同梱されているプログラム'defrobnicate'を実行する
  3. サーバを立ち上げる

 数カ月後に、また別の人が「インデックスがおかしいみたいなんです」という投稿をしてきたとしましょう。アーカイブを検索したあなたは先ほどのメッセージを見つけました。でも、そのメッセージの手順にはすこし不備があるようです(単なる間違いなのか、あるいはその当時とは仕様が変わったのかといったところでしょう)。こんなときのイケてるやり方は、作業手順をきちんとまとめ直したメッセージを新たに投稿し、そこで「以前の投稿は内容が古くなっている」と明記しておくことです。

恐らくScanleyのインデックスが狂い始めているのでしょう。

7月にも同じような投稿があり、J. Randomがそれに対して回答しています。

その回答は http://blahblahblah/blah にあります。以下に示す手順は、

J. Randomが示した手順をもう少しきちんと補足したものです。

  1. Scanleyサーバを停止する
  2. Scanleyサーバを実行しているユーザーになる
  3. そのユーザーで、'defrobnicate'プログラムを実行する
  4. Scanleyを手動で起動し、インデックスが正常になったことを確認する
  5. サーバを再起動する
(理想を言えば、古い方の投稿にメモをつけて『この内容は古くなっています。新しい情報はこちらです』といったことが指定できればいいのでしょう。しかし、わたしの知る限り、このような「新しい情報はこちら」機能を持ったアーカイブソフトウェアは存在しないようです。恐らく、アーカイブの内容の整合性を失わずにこの機能を実装するのは少し手間の掛かることなのでしょう。こういうこともあるので、よくある質問とその回答については専用のWebページを作成しておくことをお勧めするのです)

 アーカイブの使用法として最もよくあるのは、技術的な質問に対する答えを探すというものでしょう。しかし、プロジェクトにとってのアーカイブの重要性は、それをはるかに上回るものです。そのプロジェクトの公式なガイドラインがいわば「制定法」であるとするなら、アーカイブはそのプロジェクトの「慣習法」といえます。すなわち、これまでに行われたあらゆる議論の流れとその結論がアーカイブから得られるのです。以前と同じような議論を繰り返す際には、まずアーカイブを検索してみるのが義務といえるでしょう。

 そうすれば、現在の状況や予想される反論を知ることができ、それに対する反証の準備をすることができます。恐らく自分では思いつかなかった角度からの意見も見つけることができるでしょう。また、ほかのメンバーもあなたがすでにアーカイブを検索しているものとして話を進めるでしょう。たとえ以前の議論で何の結論も出ていなかったとしても、その議論を再開する際には以前の議論へのポインタを示すべきです。そうすることで、ほかのメンバーは「その議論の結論がまだ出ていない」そして「あなたがやるべきことをやっている」つまり、あなたの意見はこれまでの議論の繰り返しではないのだろうということを分かってくれます。

  • 全リソースをアーカイブと同様に扱う

 これまでのアドバイスは、単なるメーリングリストのアーカイブだけに当てはまるものではありません。特定の情報は常に同じ場所で得られるようにする、見つけやすい場所に置くなどといった原則は、プロジェクトのすべての情報に対して同様に当てはまるものです。プロジェクトのFAQを例にして考えてみましょう。

 人はFAQをどのように使うのでしょう?

  1. 適当な単語やフレーズを入力して検索できればいいですね。
  2. 単に特定の質問に対する答えを探すというだけでなく、全体をざっと眺めたいこともあるでしょう。
  3. GoogleのようなサーチエンジンでもFAQの内容を見つけられるようにしてほしいと思うことでしょう。
  4. FAQの特定の項目を直接指し示せるようにもしたいものです。
  5. FAQに新たな内容を追加できるようにもしたいでしょう。しかし、注意すべきなのは、FAQへの新たな内容の追加はFAQの検索よりもはるかに頻度の低いものであるということです。FAQは、書き込むよりも読まれる方が圧倒的に多いものです。

 1.は、つまりFAQが何らかのテキスト形式でなければならないということです。2.と3.が言わんとしていることは、FAQがHTMLページとして存在しなければならないということです。2.はさらに、HTMLが読みやすい形式であること(つまり、その見栄えを変更できること)や目次を持っていることも要求しています。4.を満たすには、FAQの各項目にHTMLの名前付きアンカーを指定しておく必要があります。それによって、ページ内の特定の場所に直接到達できるようになります。5.が意味するところは、FAQのソースファイルの取得が容易であり(章3.技術的な問題すべてをバージョン管理する項をご覧ください)、また編集しやすいものでなければならないということです。

 ここではFAQについてのみ取り上げましたが、これは、リソースの体裁を整えるほんの一例にすぎません。ここで取り上げた内容(直接検索できること、主要なサーチエンジンから検索できること、閲覧しやすいこと、特定の場所を参照しやすいこと、適切に編集しやすいこと)は、Webページ全般やソースツリー、バグ追跡システムなどでも当てはまるものばかりです。メーリングリストのアーカイブ用ソフトウェアの多くは、これらの項目の重要性に大昔から気づいていました。そのため、メーリングリストのアーカイブ用ソフトウェアの多くはこれらの機能を自前で搭載しています。そのほかの形式の文書については、担当者がそれなりに手間をかける必要があるかもしれません(このような作業をボランティアに任せていく方法は章8.ボランティアの管理で説明します)。

名前付きアンカーとID属性

Webページ内の特定の場所に直接移動させるには、名前付きアンカーを使う方法とid属性を使う方法の二通りがあります。

名前付きアンカーは単なるHTMLのアンカー要素(<a>...</a>)と同じで、そこに"name"属性を追加したものです。

<a name="mylabel">...</a>

最近のバージョンのHTMLでは、より汎用的なid属性をサポートしており、<a>だけでなく任意のHTML要素で使用できます。例えば次のように使用します。

<p id="mylabel">...</p>

名前付きアンカーとid属性の使用法は、どちらも同じです。URLの最後にハッシュマーク(#)に続けてラベルを指定すると、ブラウザはページ内のその場所に直接移動するようになります。

http://myproject.example.com/faq.html#mylabel

名前付きアンカーは事実上すべてのブラウザがサポートしており、最近のブラウザのほとんどはid属性にも対応しています。万全を期すなら、名前付きアンカーだけを用いるか名前付きアンカーとid属性を併用する(もちろん、そのときは両者に同じラベルを指定する)ことをお勧めします。名前付きアンカーは、開始要素と終了要素を1つにまとめることはできません。たとえ要素内のテキストが存在しない場合でも、以下のように開始要素と終了要素を別々に書かなければなりません。

<a name="mylabel"></a>

……とはいえ、普通はここには(セクションのタイトルなど)何らかのテキストが入るものです。

名前付きアンカーを使うにしてもid属性を使うにしても、ラベルを指定してアクセスしない限りはブラウザ上でそのラベルは見えないことに注意しましょう。しかし、例えばFAQの特定の回答をメールで示したい場合など、その場所のラベルが何なのかを知りたいこともあるでしょう。このような場合のために、"name"や"id"属性を指定した場合はtitle属性も同じ要素に指定しておくとよいでしょう。例えば次のようにします。

<a name="mylabel" title="#mylabel">...</a>

title属性を指定した要素内のテキストの上をマウスポインタが通過すると、たいていのブラウザではtitle属性の内容をポップアップ表示します。わたしは、このtitle属性の内容にハッシュマークも含めるよう心がけています。それを見たユーザーが、URLの最後にそれをつなげれば直接この場所に到達できることに気づきやすくするためです。


content on this article is licensed under a Creative Commons License.

注目のテーマ