新しいフリーソフトウェアプロジェクトをスタートさせる方法――各論：オープンソースソフトウェアの育て方（5/5 ページ）

[Karl Fogel， ]

開発者向けドキュメント

　開発者向けドキュメントを書く目的は、プログラマーがコードを理解するのを助けること、そしてコードの修正や拡張ができるようになるのを助けることです。先ほど説明した開発者向けガイドラインは技術的というよりも社会的な内容でしたが、今回説明するドキュメントはこれとは少々異なります。開発者向けガイドラインは、プログラマー同士がお互いうまくやっていくための方法をまとめたものです。一方、開発者向けドキュメントはコードそのものとうまくやっていくための方法を示すものとなります。利便性のためにこれらの2つのドキュメントが1つにまとめられていることもあります（先ほど例で示したHacker's Guide to Subversionのように）が、そうしなければならないというわけではありません。

　開発者ドキュメントがいかに有用なものであったとしても、それが原因でリリースを遅らせるようなことがあってはなりません。そのプログラムの作者自身がコードにかんする質問に答えられる（そして答える気がある）のなら、当面はそれで十分です。実際のところ、何度も何度も同じ質問に答える羽目になるっていうことがドキュメント作成の動機となることもあります。しかし、ドキュメントを書き始める前であっても、プロジェクトに協力することを決心した人たちは何とかコードと格闘しようとするものです。何が人をそこまでさせるのかといえば、そのコードがきっと何か自分の役に立つだろうと考えているからです。人がそれを信じていれば、自分自身で何とかしようとするでしょう。信じていなければ、大量の開発者向けドキュメントがあったとしてもあまり役立たないでしょう。

　なので、もしどちらか一方に向けたドキュメントしか書く時間がないのであれば、まずユーザー向けのドキュメントを作成しましょう。ユーザー向けのドキュメントは、事実上開発者向けのドキュメントでもあります。そのソフトウェアの開発に参加しようとしているプログラマーは、まずそのソフトウェアの使い方を身に着けなければならないからです。後になってほかのプログラマーが同じような質問を何度も何度も繰り返すようになったときに、あらためて時間をとってドキュメントを作成すればいいでしょう。

　プロジェクトによってはwikiを用いてドキュメントを書き始めるところもあります。それどころか、wikiをメインのドキュメントとしているところもあります。わたしの経験上、これはあまりうまくいかないものです。もしうまくいくとすれば、それはドキュメントの構成をしっかり把握し、そこに何を書くべきかを熟知した数人の人間が頻繁にwikiを更新している場合のみでしょう。詳細は、章3.技術的な問題のWiki項をご覧ください。

使用例とスクリーンショット

　そのプロジェクトがグラフィカルなユーザーインタフェースを持っていたり、グラフィカルあるいはそうでない特徴的な出力を行ったりする場合は、そのサンプルをプロジェクトのWebサイトに公開しておきましょう。インタフェースの場合は、スクリーンショットがこれに当たります。出力の場合は、同じくスクリーンショットか、あるいは実際の出力ファイルとなります。これはどちらも、即座の満足感に対するユーザーの欲求を満たすものです。長々とした説明やメーリングリストでのやり取りよりも、ほんの一枚のスクリーンショットの方が説得力を持つこともあります。なぜなら、スクリーンショットはまさにそのソフトウェアが動作した結果であることに疑いの余地がないからです。バグだらけかもしれません。インストールが難しいかもしれません。ドキュメントが足りないかもしれません。でも、スクリーンショットさえあれば、何とかがんばれば動かすことができるんだということの証明になります。

スクリーンショット

　作ったことがない人にとっては、スクリーンショットの作成は大変なものに感じられるかもしれません。そこで、ここではその基本的な方法を説明します。Gimpを立ち上げて、メニューからFile->Acquire->Screenshotを選び、Single WindowあるいはWhole Screenのいずれかを指定してOKをクリックします。その次にマウスでクリックしたウインドウあるいはスクリーンが、Gimpに画像として取り込まれます。後は、必要に応じて画像の一部を切り出したりサイズを変更したりします。その方法はこちらで説明されています。

　プロジェクトのWebサイトに置くことのできる情報は、これら以外にもたくさんあります。最新情報のページやプロジェクトの歴史のページ、関連サイトへのリンク、サイト内検索の機能、寄付の受付などです。もし時間が許したり何か特別な理由があるのなら、これらを作成してもよいでしょうが、プロジェクトの立ち上げ時には通常はどれも不要です。しかし、将来のために心にとどめておきましょう。

公開場所

　オープンソースプロジェクトのために、Webサイト用の領域やバージョン管理機能、バグ追跡システム、ダウンロードエリア、掲示板、バックアップなどの機能を無料で提供するサイトが幾つかあります。詳細はサイトによって異なりますが、基本的な機能はどこでも同じようなものです。これらのサイトのいずれかを使用すると、無料で多くのものを手に入れることができます。ただ、ユーザーへの見せ方をきめ細かく調整するといったことはあきらめなければなりません。そのサイトでどんなソフトウェアを用いるのかを決めるのはホスティング業者であり、プロジェクトのWebページの見た目はその業者に多少なりとも左右されることになります。

　あらかじめ用意されているホスティングサイトを使うことの利点と欠点、ホスティングサイトの一覧などについての詳細は、章3.技術的な問題のツールが一通りそろったホスティングサイト項をご覧ください。

著者：Fogel Karl

翻訳者：高木 正弘

翻訳者：Takaoka Yoshinari(a.k.a mumumu)

製作著作 © 2005, 2006, 2007, 2008, 2009 Karl Fogel, 高木正弘, Yoshinari Takaoka(a.k.a mumumu), under a CreativeCommons Attribution-ShareAlike (表示・継承) license (3.0, 2.1-jp)

よいフリーソフトウェアを作ることは本質的に価値のある目標です。その方法を模索している読者の皆さんが、本連載「オープンソースソフトウェアの育て方」で何かのヒントを得てくだされば幸いです。

原文へのリンク