オープンソースプロジェクトのドキュメントで避けるべき 13 の事項-php手册-php.cn

ほとんどのオープンソースプロジェクト開発者は、ソフトウェアの品質のみに焦点を当てており、高品質のドキュメントを作成することを忘れていることがよくあります。ただし、ドキュメントの品質はプロジェクトの成功に重要な役割を果たします。これは、ユーザーがプロジェクトを迅速に理解したり、ユーザーの使用中に何らかの助けを提供したりするのに役立ちます。

しかし、多くのオープンソースプロジェクトのドキュメントは、主に次の点で残念なものです。

1. 適切な README または紹介文の欠如

README は、潜在的なユーザーにプロジェクトを事前に迅速に理解させることができます。プロジェクトが GitHub 上にある場合、README ファイルはプロジェクトのホームページに自動的に表示されます。ユーザーをすぐに引き付け、プロジェクトを探索し続けたい場合は、優れた紹介が不可欠です。プレゼンテーションが悪ければ、こうしたユーザーは戻ってこない可能性があります。

README ファイルには少なくとも次のものが含まれている必要があります:

プロジェクトの目的
群衆に向けて
実行中のプラットフォームまたはハードウェア
重要な依存関係
インストール方法、またはさらに詳しい説明

プロジェクトの README は、あなたのプロジェクトについて聞いたことがない人向けに書かれなければなりません。たとえば、プロジェクトにはレーベンシュタイン距離を計算するモジュールがあります。README を読んでいる人全員がレーベンシュタインのことを知っているとは思わないでください。人々がさらに詳しく調べられるように、それを説明し、関連する詳細へのリンクを含める必要があります。

新しいものを紹介するとき、「NumberDoodle は BongoCalc に似ていますが、それよりも優れています」など、他の新しいものを紹介しないでください。BongoCalc をまったく知らない人もいるかもしれません。

2. オンラインで入手できるドキュメントはありません

プロジェクトのドキュメントは Google で検索できる必要があるため、ドキュメントがオンラインで利用できることを確認してください。

以前、オープンソースプロジェクトをリリースしましたが、イライラしたのは、FAQ ですでに回答した質問をユーザーが頻繁に電子メールで私に送ってきて、後から FAQ を Web サイトに掲載していなかったことが判明したことでした。作成者はユーザーの観点から問題を考慮していないため、これは比較的犯しやすい間違いです。

3. オンライン文書のみが提供されます

オンラインドキュメントを提供しないことはできませんが、オンラインドキュメントだけを提供することもできません。一部のプロジェクトの最終バージョンにはドキュメントが含まれていない、またはプロジェクト開発段階からの不完全なドキュメントが含まれており、最終ドキュメントはオンラインに配置されているため、インターネットにアクセスできないユーザーにとっては特定の問題が発生します。

たとえば、Solr プロジェクトには非常に包括的な Wiki (ドキュメント) がありますが、ダウンロード用に提供されているのは 2,200 ページの自動生成された API Javadoc であり、エンドユーザー向けのドキュメントは 1 ページのチュートリアルのみです。

PHP 言語パックにはドキュメントも付属していません。ドキュメントが必要な場合は、別のページに移動する必要があります。残念ながら、ダウンロードできるのはコアドキュメントのみであり、ユーザーを助けるコメントはありません。

オープンソースプロジェクトは、すべてのユーザーがインターネットにアクセスできることを当然のこととは考えません。また、ユーザーをプロジェクト Web サイトに過度に依存させることもできません。過去数か月の間に、Solr wiki が少なくとも 2 回ダウンするのを目撃し、難しい設定の問題を解決するのに大慌てでした。

この点でより優れているのは、Perl とその CPAN モジュールライブラリです。各モジュールのドキュメントは、search.cpan.org およびmetacpan.org で読みやすいハイパーリンク形式で提供されています。オフライン環境の場合、各モジュールのドキュメントはコード自体に埋め込まれており、ユーザーがモジュールをインストールすると、ローカルドキュメントが取扱説明書として自動的に作成されます。ユーザーは、シェルで perldoc Module::Name コマンドを使用してドキュメントを取得することもできます。オンラインでもオフラインでも使用できます。

4. ドキュメントは自動的にインストールされません

これは通常、パッケージ作成者のせいです。たとえば、Ubuntu Linux では、Perl 言語ドキュメントは独立したオプションのパッケージであるため、ユーザーはインストール中にこのオプションを見逃す可能性があります。数 MB のディスク領域が節約されますが、ユーザーは必要なときにそれを見つけることができません。

5. スクリーンショットがありません

時には、百聞は一見にしかずです。

スクリーンショットは、ユーザーが操作の結果を視覚的に比較して、各タスクが正しく完了したかどうかを確認したり、問題が発生した場所を簡単に特定したりするのに役立ちます。

最近では、複雑なプロセスの手順を示すビデオを使用してプロジェクトを紹介することも一般的になっています。たとえば、Plone プロジェクトには、ビデオチュートリアルを提供する専用 Web サイトがあります。ただし、ユーザーはビデオで何かをすぐに見つけることができない（少しずつ見る必要がある）ため、ビデオはまだスクリーンショットの代わりにはなりません。また、ビデオは Google 画像検索に含めることができませんが、スクリーンショットは含めることができます。

6. 実例の欠如

コードベースのプロジェクトの場合は、スクリーンショットも有効ですが、例を示す方がより実用的です。これらの例は抽象的なものではなく、現実世界からのものである必要があります。開発者は、時間をかけて関連する例を作成し、プロジェクトが問題をどのように解決するかをユーザーに示す必要があります。

Apache プロジェクトの Rich Bowen 氏は、「正しく、完全に機能し、テストされ、コメントが付けられたサンプルは、退屈な紹介文の 1 ページ分の価値があります。」と述べています。

7. リンクと参照がありません
説明している内容が文書の一部であるから、またはユーザーがすでに読んでいるから、または文書の場所を知っているから、ハイパーリンクを使用する必要がないと考えないでください。たとえば、プロジェクト内のコードの一部が frobbitz オブジェクトを操作するものである場合、frobbitz オブジェクトについて説明するか、関連ページへのリンクを作成する必要があります。

8. 新規ユーザーは考慮されません

ドキュメントを作成するとき、一部のユーザーが詳細を説明せずにすでに何かを知っていると想定しないでください。新しいユーザーを考慮し、最適な例を含む別のページを使用して、新しいユーザーをプロジェクトにすぐに紹介する必要があります。

9. ユーザーのフィードバックに耳を傾けない
「このプログラムのインストールに役立つ、データベースドライバーのインストールに関する紹介やリンクがあればいいのに」など、ソフトウェアを使用するユーザーの提案やニーズに積極的に耳を傾ける必要があります。
ユーザーからのフィードバックに基づいて FAQ を作成します。また、StackOverflow などの他の Web サイトやフォーラムをフォローし、Google アラートを作成して、インターネット上のプロジェクトに関する議論を知ることもよくあります。

10. ユーザー入力を受け入れません
プロジェクトに十分な規模のユーザーベースがある場合は、ユーザーがドキュメントにコメントを直接書き込める機能を提供することを検討してもよいでしょう。私が見た中で最も良い例は PHP です。ドキュメントの各ページでは、認証されたユーザーがそのページにコメントしたり、コア以外のドキュメントの例を追加したりできます。

時間の経過とともに古い注釈が表示され、これらを廃止する必要があるため、このコンテンツは維持する必要があります。

11. プロジェクトの目的を理解するにはインストールする必要があります
すべてのソフトウェアプロジェクトには機能リストとページのスクリーンショットが必要です。ライブラリなどの純粋なコードプロジェクトの場合は、サンプルページも必要です。

12. ドキュメントの自動生成に依存する
ほとんどの場合、ソフトウェア開発者は自動ドキュメント生成システムを使用して自分の作業を置き換えます。他にも手動で書かなければならない部分があることを忘れてしまいます。

最悪のシナリオは、変更ログに一部のコミット情報以外は何も存在しないことです。変更ログには、新機能、バグ修正、および潜在的な互換性の問題がリストされる必要があり、その対象グループはエンドユーザーです。送信ログは開発者が見ることができます。

13. 初心者ユーザーを傲慢に扱う
ユーザーの質問に「RTFM (おかしなマニュアルを読んで、TMD マニュアルを読んでください)」という態度で応答しないでください。これは、潜在的なユーザーのグループを怖がらせてしまう可能性があります。

ユーザーの問題がドキュメントに記載されているにもかかわらず、ユーザーがそれを実行しないとしても、それを愚かなことだと思わないでください。ドキュメントの書き方が不十分、読みにくい、または不完全である可能性があります。「はじめに」の章を根気よく改善して、ソフトウェアの目的を説明したり、関連情報の入手先をユーザーに示したりする必要があります。

英語原文: 13 Things People Hate about Your Open Source Docs