FOSSアプリケーション用ドキュメント作成をwikiを活用して行う際のヒント
一口にソフトウェアのドキュメント作成と言っても、その範囲、スケール、目的は個々のプロジェクトごとに異なってくるものだが、カバーすべき基本アイテムについては共通しているはずだ。いずれにせよこの種のプロジェクトを幸先よく立ち上げるには、事前に下記の点に関する若干のプランニングと必要事項の確認を行っておかなくてはならない。
- ドキュメント類の作成と編集を誰が担当するか
- その作成とメンテナンスにはどのようなツールを使用するか
- どのような情報をどのような形で提示する必要があるか
ドキュメント作成チームの結成
これらの検討事項は比較的簡単に決められる内容のものであるが、それでも作業に携わるメンバ間では、討論をした上での合意を得ておく必要がある。現実問題としてこの種の作業における合意とは、新たな試みに取り組むことを各自が承知するということであり（例えばサイトのアウトラインなど）、ドキュメントの作成過程で新たな変更を追加する可能性を納得させておくということでもある。つまりソフトウェアのドキュメントとは、実際の作業に取りかかる以前にその完成形態を完全に予想しておく必要のない性質のものなのだ。
コミュニティに属すユーザ全体のニーズをカバーするドキュメントを作成するためには、開発者およびエンドユーザの双方を含めて、あらゆるタイプの関係者の意見を集めるようにしなければならない。つまり開発者以外の人間による協力は不可欠なのであり、そうした協力者については意図的に呼び集めるようにすべきである。src2pkgの場合、ドキュメント作成の担当者を決めるのは比較的簡単であった。src2pkgの作成者であるGilbert Ashley氏はLinuxQuestions.orgの貢献者でもあって、その場を借りる形で自分の作成したプログラムに対するユーザからの質問に答えており、今回の作業に参集した私たち3名は日頃からSlackwareフォーラムにて同氏の活動をサポートしていたのである。
意図しての結果か単なる偶然かは不明だが、私たち3名の協力者は背景をかなり異にするユーザどうしであった。私自身は最末端のエンドユーザであり、他の2名はsrc2pkgの開発内容にまで立ち入った発言のできる上級レベルのユーザという構成であったため、私たちの間での作業分担も個々の得意分野に合わせる形で自然と定まってしまったのだ。私自身は以前に技術系ドキュメントの作成と編集に携わっていた経験を有していたので、今回のプロジェクトでも同様の作業を担当することになり、もう1名の協力者であるPiete Sartain氏はWebでのホスティングに関する経験があったため、Webサーバにwiki用ソフトウェアをインストールしてその設定を行う作業を担当することになった。このように作業内容の分担に関する合意を当事者間で得ておくか、あるいは最低限でも各自が集中すべき分野を自主的に申し出るようにして、扱いやすい個別的なタスクにプロジェクト全体を分割する必要がある。
私たちの間で討議したのは、一般ユーザからの貢献を無制限とするか特定のメンバのみに制限するかである。今回は、サイトのセットアップを進めていく段階では制限を課しておき、将来的にはオープンな貢献を認める余地を残すという方針に決定した。その他の選択肢としては、協力を申し出た人間に対してサイト管理者がアカウントを発行するという方式も取り得たであろう。この方式はサイトがwikiスパムの攻撃に曝される危険性も少なく、個々の作業内容に目を光らせて品質を維持するのも簡単なはずである。src2pkgは小振りなアプリケーションであってユーザ数も限られているので、このソリューションは私たちのプロジェクトにて有効に機能したと思われる。ただし1つのLinuxディストリビューション全体をカバーするwikiを立ち上げるといった場合は、そこで扱うトピック数もかなりな量に上るので、これとは異なるアプローチを必要とするだろう。
使用するツールの選択
今回、ドキュメントの作成と管理をwiki形式で行うのは半ば暗黙のうちに決定されていたが、問題となったのは実際にどのwikiパッケージを使用するかの選択であった。ここで言うwikiソフトウェアとは、任意の貢献者によるWebページの直接的な変更を許可し、そうした人々の行った変更内容を追跡する機能を有しているツールのことである。特定の内容に関するドキュメントやWebサイトを世界各地に離散したユーザが協力して作成する手段としてwikiが普及したのは、わずかここ数年の出来事でしかない。
今回のプロジェクトにおいて候補として検討したソフトウェアは、Wikipediaでも使われているMediaWikiおよび、DokuWikiの2つであった。私たちは結局これらを2つとも試したのである。最初はMediaWikiの方が親しみやすくプロフェッショナルレベルの機能を備えているよう感じられた。実際このツールでのマークアップ作業は直感的に行えるようになっており、テキストの挿入やフォーマットもスムースに進行したのだが、収めるべき大半のテキストをMediaWikiバージョンにてサイトに格納した後、私はDokuWikiバージョンでの再フォーマットを行うよう決断した。とは言うものの、確かにDokuWikiのツールバーは若干ながらMediaWikiのものよりも機能的に豊富であり操作も簡単であったのだが、最終的なテキスト編集の作業負担はごくわずかに軽減されたに過ぎない。
つまり私たちが敢えて途中でDokuWikiに切り替えた理由はこうした編集用インタフェースの優劣ではなく、DokuWikiの場合はカスタマイズが容易であると同時に、管理が行い易かったからなのである。例えばDokuWikiは“nstoc”という名称のプラグインを介することでサブディレクトリ群に格納されたコンテンツを一覧化することができ、当方が求めていた、変更を加えるごとにコンテンツのマスタテーブルをアップデートさせたいという要望に合致していたのだ。あるいはMediaWikiにもこの機能は実装されていたのかもしれないが、少なくとも何らかの手間をかけないと実装できないと私たちは判断したのである。その他にDokuWikiを選択した理由としては、MediaWikiと異なってディスカッションページなどのオープンなコラボレーション活動を前面に押し出した作りになっていなかった点を挙げられる。一見するとこれはデメリットのように感じられるかもしれないが、パスワードによるアクセス制限を施された特定数の貢献者だけがコンテンツを登録するという私たちのプロジェクトにとってはメリットとして機能したのである。
コンテンツの構築と整理
src2pkgの場合に遭遇した困難の1つは、既存のドキュメント類を整理統合して、然るべき位置に再配置し直すことであった。他のプロジェクトの場合、こうしたコンテンツは既存のものをブラッシュアップするのではなくゼロから構築する場合もあるだろうが、いずれにせよサイトの全体的な構成を定めるアウトラインを規定しておくことは大いに役立つはずである。こうしたアウトラインの特定は、これから作成するwikiのロードマップとしての意味を持つだけではなく、コラボレーション態勢下で作業を進める際の基本ツールとしても機能するからだ。実際に私も、わずか2階層という簡単なものではあるが、暫定的に定めたアウトラインの草稿を電子メールにて作業に携わる他のメンバに通達しておいた。その後電子メールでのやりとりを何度か繰り返した後、最終的に3階層に改められたものが実務に供すレベルのワーキングアウトラインとして使われるようになったのである。なお私がアウトラインの草稿を作成した際には、既存ドキュメントの内容をそれほど重視してはいなかった。その代わりに私たちはエンドユーザと開発者という双方の立場からドキュメントとしてまとめるべきコンセプトを徹底的に論じあい、そうしたコンセプトを達成する上で不可欠なディテールと、その整理すべき順番を煮詰めておいたのである。その後形成されたワーキングアウトラインについての合意は速やかに得ることができており、src2pkgのwiki作成に関する残りの作業はその分だけ促進されたと見ていいだろう。
次に行ったのは既存の全ドキュメントに目を通して、ワーキングアウトラインに則した形態で整理し直すことであった。先に触れたMediaWikiとDokuWikiの比較を行ったのは主としてこの作業プロセスであり、こうした作業を進めて行くに従いフォーマットその他の機能の実態が把握できたのである。同時にここでは先に定めておいたワーキングアウトラインの有用性も証明されることになり、末端の第3階層において若干のヘッダ追加を行った以外、上位2階層に関しては何らの変更も施す必要はなかった。具体的な作業内容としては、近接する段落をまとめてwiki上の別セクションに移動するといったものが多かったが、これによりsrc2pkgを使用する際に必要となる情報および、その機能を最大限に発揮させる活用法を、より組織だった形態で提示できるようになったはずである。
行うべき作業は現状でまだいくつか残されている。例えば文章のスタイルを始め、用いる文法や用語および全体的なフォーマットを統一するには、よりいっそうの編集作業が必要となるはずだ。より重要なのは、一部のトピックが空欄のまま放置されている点である。もっともこれらの空欄トピックに関しても事前に定めておいたアウトラインを基にヘッダだけは設けてあるので、テキストを追加すべき箇所は簡単に特定することができるし、コンテンツの不足分についても、協力者間で電子メールにて依頼をすることで誰がどのトピックを執筆するかの手配は比較的簡単に済むはずだ。
最後に残された問題は、コンテンツを常に最新の内容に維持し続けることである。特にこの種の情報については開発者サイドが変更履歴を提供していくことが重要で、場合によっては個々のアップデートごとに“変更に関する情報”をテキストファイルに書き下してドキュメント管理の担当者たちに提供しなくてはならない。
まとめ
ドキュメントの整備というプロジェクトは、そのカバーすべき範囲が限られている場合であっても非常に多数の作業を伴うものである。確かにwikiソフトウェアを活用すれば、インターネットを介してコラボレーション形態で進めるプロジェクトを効率化することはできるものの、キーボード上で行うテキストの作成と編集に要する作業時間はそれほど削減できる訳ではない。
この種のプロジェクトを成功に導く鍵は、行うべき作業の80％は既に着手済みであると、貢献者全員に感じさせることである。コラボレーションを促進して他の人間の協力を得る最善の方法は、自らが主体的に作業を進めておき、自分以外のメンバにはその改善を要請するだけにしておくことだ。また特定のソフトウェアに関するドキュメント整備というケースでは、自らの行うハードワーク以外にも、様々なユーザ層をカバーした人員を集めたチームを結成した上で、ニーズに則したwikiパッケージを選定し、コンテンツ整理のガイドとなる確固としたアウトラインを確定しておくことが不可欠である。
Drew Amesは、ペンシルバニア州ハリスバーグにてトランスポーテーションプランナとして活動している。
