FOSSアプリケーション用ドキュメント作成をwikiを活用して行う際のヒント

 多くのプログラマにとってアプリケーションのコードを記述するのは楽しい作業だが、そのマニュアルを記述するのは苦痛だと感じられていることだろう。アプリケーションとしての完成度を高めたり、新規機能の追加やユーザから寄せられた要望を実現する方が、ソフトウェアの操作法を文章として書き下すより得られるものが多いからだ。とは言うものの、将来的な開発作業を積極的に支えてくれるユーザをつなぎ止めておくには、分かりやすいドキュメント類を整備しておくことも不可欠である。私を含めた数名の協力者がsrc2pkg(Slackwareの“magic package maker”)の作成者であるGilbert Ashley氏の下に参集して、同氏の開発するプログラムのユーザドキュメントの整備をサポートし始めたのは数カ月前のことであった。本稿ではその際に行った src2pkg wiki の立ち上げプロセスを簡単に解説するが、その際に得られた教訓は、その他のフリー/オープンソース系ソフトウェア(FOSS)アプリケーション開発者にとっても参考になることであろう。

 一口にソフトウェアのドキュメント作成と言っても、その範囲、スケール、目的は個々のプロジェクトごとに異なってくるものだが、カバーすべき基本アイテムについては共通しているはずだ。いずれにせよこの種のプロジェクトを幸先よく立ち上げるには、事前に下記の点に関する若干のプランニングと必要事項の確認を行っておかなくてはならない。

  • ドキュメント類の作成と編集を誰が担当するか
  • その作成とメンテナンスにはどのようなツールを使用するか
  • どのような情報をどのような形で提示する必要があるか

ドキュメント作成チームの結成

 これらの検討事項は比較的簡単に決められる内容のものであるが、それでも作業に携わるメンバ間では、討論をした上での合意を得ておく必要がある。現実問題としてこの種の作業における合意とは、新たな試みに取り組むことを各自が承知するということであり(例えばサイトのアウトラインなど)、ドキュメントの作成過程で新たな変更を追加する可能性を納得させておくということでもある。つまりソフトウェアのドキュメントとは、実際の作業に取りかかる以前にその完成形態を完全に予想しておく必要のない性質のものなのだ。

 コミュニティに属すユーザ全体のニーズをカバーするドキュメントを作成するためには、開発者およびエンドユーザの双方を含めて、あらゆるタイプの関係者の意見を集めるようにしなければならない。つまり開発者以外の人間による協力は不可欠なのであり、そうした協力者については意図的に呼び集めるようにすべきである。src2pkgの場合、ドキュメント作成の担当者を決めるのは比較的簡単であった。src2pkgの作成者であるGilbert Ashley氏はLinuxQuestions.orgの貢献者でもあって、その場を借りる形で自分の作成したプログラムに対するユーザからの質問に答えており、今回の作業に参集した私たち3名は日頃からSlackwareフォーラムにて同氏の活動をサポートしていたのである。

 意図しての結果か単なる偶然かは不明だが、私たち3名の協力者は背景をかなり異にするユーザどうしであった。私自身は最末端のエンドユーザであり、他の2名はsrc2pkgの開発内容にまで立ち入った発言のできる上級レベルのユーザという構成であったため、私たちの間での作業分担も個々の得意分野に合わせる形で自然と定まってしまったのだ。私自身は以前に技術系ドキュメントの作成と編集に携わっていた経験を有していたので、今回のプロジェクトでも同様の作業を担当することになり、もう1名の協力者であるPiete Sartain氏はWebでのホスティングに関する経験があったため、Webサーバにwiki用ソフトウェアをインストールしてその設定を行う作業を担当することになった。このように作業内容の分担に関する合意を当事者間で得ておくか、あるいは最低限でも各自が集中すべき分野を自主的に申し出るようにして、扱いやすい個別的なタスクにプロジェクト全体を分割する必要がある。

 私たちの間で討議したのは、一般ユーザからの貢献を無制限とするか特定のメンバのみに制限するかである。今回は、サイトのセットアップを進めていく段階では制限を課しておき、将来的にはオープンな貢献を認める余地を残すという方針に決定した。その他の選択肢としては、協力を申し出た人間に対してサイト管理者がアカウントを発行するという方式も取り得たであろう。この方式はサイトがwikiスパムの攻撃に曝される危険性も少なく、個々の作業内容に目を光らせて品質を維持するのも簡単なはずである。src2pkgは小振りなアプリケーションであってユーザ数も限られているので、このソリューションは私たちのプロジェクトにて有効に機能したと思われる。ただし1つのLinuxディストリビューション全体をカバーするwikiを立ち上げるといった場合は、そこで扱うトピック数もかなりな量に上るので、これとは異なるアプローチを必要とするだろう。