オープンソース・ドキュメントについて：プログラマが無視する可能性がある10のこと

オープンソースプロジェクトのドキュメントの多くは、主に以下のいくつかの点から非常に失望しています。

　　1.良い自己紹介や紹介が欠けている

Readmeは、潜在的なユーザーがあなたのプロジェクトに対する第一印象です。プロジェクトがGitHubにある場合、Readmeはプロジェクトのホームページに自動的に表示されます。もしあなたが少しうっかりして自己主張を間違えたら、これらの潜在的なユーザーは二度と戻ってこない可能性があります。だから、あなたのプロジェクトには、ユーザーがあなたのプロジェクトに興味を持っていることをアピールするための良いReadmeが必要です。

Readmeファイルには、少なくとも次の点の説明が含まれている必要があります。

●何のプロジェクトですか。

●どのようなユーザーに向けているのか、

●どのハードウェアまたはプラットフォーム上で動作しているか、

●主な依存関係、

●方向指針をどのように取り付けたり、深く入れたりするか。

これらは、あなたのプロジェクトを聞いたことがないユーザーや、あなたのプロジェクトを永遠に考えない可能性があるユーザーに書かれています。もちろん、あなたのReadmeを読んでいるすべてのユーザーがそれが何であるかを知っていると思ってはいけません。必要なときには注釈を作成したり、有用なリンクを添付したりして、ユーザーがあなたのプロジェクトを理解しやすくする必要があります。

　　2.オンラインドキュメントを提供しない

この方面の研究調査は見たことがありませんが、文書の90%はグーグルやインターネットの他のブラウザで検索されていると思います。したがって、ドキュメントはオンラインで使用可能である必要があります。この点はどうやって発見したのでしょうか。多くのユーザーがFAQの答えを見ずに、ネット上から質問の答えを検索することが多いため、プロジェクトに問題が発生することがよくあります。そのため、オンラインのドキュメントを提供することで、ユーザーが問題を解決するのに役立ちます。

　　3.オンライン文書のみ

この問題のもう1つの側面は、開発者がオンラインのドキュメントだけを提供することです。プロジェクトによってはインタラクティブなドキュメントが付属していないものや、含まれているドキュメントが不適切なバージョンであるものもあります。例えば、PHP言語にはドキュメントが付属していません。ドキュメントが必要な場合は、別のページで開く必要があります。しかし、さらに悪いことに、コアコードだけがダウンロードできる。これにより、ユーザーは自分に役立つ情報を得ることができなくなる可能性があります。

オープンソースプロジェクトは、ユーザーがインターネットにアクセスする際にオンラインのドキュメントが必要だと考えることはできません。もちろん、ユーザーがあなたのプロジェクトサイトに過度に依存することを望んでいません。

　　4.インストールドキュメントを含まない

この問題は通常、プロジェクト開発者の問題ではなくパッケージの作成者の問題です。例えばUbuntu Linuxオペレーティングシステムでは、Perl言語選択のパッケージ自体が個別のドキュメントになっています。ユーザーは、問題が発生したときにユーザーがタイムリーに解決できるように、インストール時に必要なインストールドキュメントとコア言語のドキュメントを知っておく必要があります。

　　5.スクリーンショットの欠如

潜在的なユーザーの注意を得る方法や、ソフトウェアの正しい使い方を説明する方法はありますか。賢明な方法はスクリーンショットです。インターネット時代には、1枚の図が千言万語に勝るかもしれない。スクリーンショットは、ユーザーが自分の使い方が正しいかどうかを判断することができ、自分の間違った場所を見つけることもできます。したがって、必要なスクリーンショットはオープンソースドキュメントにとっても重要です。

　　6.例がない

コードベースのプロジェクトでは、シミュレーションのスクリーンショットは非常に良いですが、関連するインスタンスも少なくありません。これらのインスタンスは抽象的ではなく、現実世界から抽出されるべきである。時間をかけてプロジェクトに関連するインスタンスを作成し、ソフトウェアの使用中に発生した問題を解決する方法をユーザーに示します。

　　7.不十分なリンクと参照＃サンショウ＃

ハイパーリンクがある場合は、ドキュメントで使用してください。ユーザーがドキュメントを読んで理解できると思ってはいけません。ドキュメントの中には、ユーザーが理解できていないものが一部存在する可能性があります。この場合は、ユーザーが問題を解決するためにすべてのハイパーリンクと参照を使用する必要があります。

　　8.新規ユーザーを忘れる

ドキュメントを書くときは、ソフトウェアの開発者にとって簡単に、開発者自身の視点に立って作成します。しかし、新しいユーザーにとっては、入門ドキュメントが必要です。新しいユーザーができるだけ早くソフトウェアを理解したり、ソフトウェアの使い方をマスターしたりするためには、ユーザーのための入門文書を書くために別のページを使用するべきだと思います。

　　9.耳を貸さないユーザー要件

プロジェクトの開発者は、プロジェクト全体に対するユーザーのニーズに耳を傾ける必要があります。最も効果的な方法は、より多くの人にあなたのプロジェクトを試してもらい、問題を見つけることです。同様に重要なのは、ユーザーのニーズに耳を傾ける過程で、プロジェクト開発者はユーザーがこれらの問題を提起した背後にある本当の理由を考慮しなければならない。

　　10.受け入れないユーザー入力

プロジェクトに十分なユーザーグループがある場合は、ユーザーに直接コメントをドキュメントに追加させることができます。私が見た最良の例はPHP言語で、文書内の各ページで認証されたユーザーがコメントを追加できるようにしたり、追加されたコメントはコア文書に含まれていません。