コードをオープンソース開発ツールのドキュメントにすることはできますか？どのくらいの頻度ですか？
大規模な開発努力の後、一部のOSS作成者は、プロジェクトのユーザーも開始するために努力する必要があると合理的に見なしていることは理解できます。
ソースコードを効果的にプロジェクトのドキュメントにすることはできますか？これを達成するために、特定の方法で構造化する必要がありますか？そして、このアプローチはどのくらいの頻度で採用されていますか？
もちろん、これは、プロジェクトが開発者を対象とし、アプリケーションの同じターゲット言語で書かれている場合にのみ実現可能です（たとえば、 V8エンジン JavaScriptしか知らない場合など）。
NHibernateはOSSです。ソースコードを無料でダウンロードしたり、独自の変更を加えたり、再コンパイルしたり、そのソースコードをVCSにプッシュバックしたりできます。Ayendeでは、効果的に使用するために、コードとCastleのDynamicProxyのコードを掘り下げる必要がありますか？あなたの永続層を実装するための彼のライブラリ？もちろん違います。 NHibernateコミュニティは、NHibernateライブラリを使用するための非常に優れたドキュメントとベストプラクティスのセットを提供します。同様に、FluentNHアドオンには適切なドキュメントがあります。ライブラリの機能と使用方法を理解するために、ライブラリのコードを掘り下げる必要はありません。
つまり、OSSでさえ、エンドユーザーの観点から「ブラックボックスの原則」に準拠する必要があります。
コーダーは、ライブラリが電子機器と同じようにパッケージ化されることを期待しています。この「ブラックボックス」と一緒に、ライブラリの接続方法と通信方法を説明した取扱説明書を受け取ることを期待しています。彼らがマニュアルを受け取らない場合、彼らの中で賢い人はパッケージに何が入っているかを見て、物がどこに差し込まれるかについて非常に明確なラベルを見ると期待し、一度それを操作するのに特別な知識は必要ないと仮定します正しく設定されています。これらのどちらも当てはまらない場合、TiVoのセットアップに必要なすべての情報がない場合にテクニカルサポートに電話するのと同じように、コーダーはライブラリの開発者に助けを求めるでしょう。 lastは、保証された新品の機器のシールを破り、最後のように自分でトレースしてみます。コーダーが行うことは、ライブラリのソースコードをプルアップしてトレースし、その内部の仕組みに関する手がかりを探すことです。
同様に、コード以外の方法で効果的に文書化されていないOSSプロジェクトは、次の3つのカテゴリのいずれかに分類されます。
- 幼児プロジェクト-概念実証、つまり機能するコードに焦点が当てられているため、ドキュメントはまだ十分に開発されていません。この段階のコードのユーザーは「ベータ」テスターであり、ドキュメントを含むすべての面でその「現状のまま」の性質を理解しています。
- 非常に単純-ライブラリの指定された目的、オブジェクトブラウザまたはJavaDocing the JARから見たクラスとクラスメンバーの名前と署名、およびおそらく簡単なデモで、ユーザーにすべてを伝えます知っておく必要があります。
- 死んでいるか死にかけている-試行錯誤や検査によってライブラリの使い方を理解するのに時間をかけたくないので、誰もそれを使用していません。
ソースコードはドキュメントではありません。
ドキュメントがなく、ソースコードといくつかのチュートリアルしかない（優れた）プロジェクトが多すぎます。私の最新の例はLuteceです（フランスのCMS：それを使用する方法とそれを使って何ができるかを理解するために多くの時間を費やしました。それはひどいものでした）。
理想的には、アプリケーションを開発するときにドキュメントが作成されます。残念ながら、多くの人はドキュメントを作成せず（Javadoc for Java projects、...）ではなく、寄稿者がチュートリアル、ウィキ、ドキュメントを作成すると思います。最初のドキュメントがない場合、誰もあなたを助けようとせず、あなたの仕事を発見しようとはしません。
良いドキュメントを作成でき、十分な時間があれば、作成してください;）
いいえ、コードはbeドキュメントであるべきではないと思います。そして、それがオープンソースプロジェクトであるかどうかはそれほど重要ではないと思います。
（コード自体以外の）ドキュメントの欠如は、多くの潜在的なユーザーや貢献者にとってはオフになります。非常に乏しいチュートリアルが非常に単純すぎて（実際のビジネスでの使用はより複雑で、明確に説明または文書化されていない機能が必要だった）、APIドキュメントがほとんどなかったという理由だけで、他のオープンソースライブラリにいくつかのライブラリを使用することをやめたり避けたりしましたfunction: SetParamX() - This sets param X以上。コードだけでは、param X must be a valid subnet mask, unless param Y is set to "foo"などの高レベルのビジネス要件や仕様を簡単にキャプチャすることもできません。この要件を推測するには、100行のコードを読み、3層または4層のメソッド呼び出しをジャンプして、この要件が正確に何であるかを確認する必要がある場合があります。
あなたあなたは、コードだけから自分自身を解読したプロジェクトに取り組むことにどれほど熱心でしょうか？それがオープンソースプロジェクトであろうと、社内の企業プロジェクトであろうと、私はそうしないことを知っています。少なくとも内部プロジェクト（少なくともここでは）では、これが問題になることはめったにありませんが、決してありません）-そしてそれが内部プロジェクトで発生した場合、私はおそらく、コードを書いた人を見つけて質問することができます。
Wordのドキュメントには多くの意味があります。ほとんどのオープンソースプロジェクトでは、これが問題になります。
多くの詳細はさておき、私は主にそれを3つの部分に分類します-
エンドユーザーのドキュメント-人々が最終製品のみを使用する可能性が高い場所。 OSSプロジェクトで最も一般的で最小限のものは、「manページ」です。
APIドキュメント-ここでは、人々がモジュールの内部を見ているが、ブラックボックスとしてのみ見ていると想定しています-主にライブラリをリンクすることによって。 （たとえば、ビデオコーデックライブラリを使用して独自のメディアプレーヤーを構築します）。優れた例の1つは、アプリケーション開発者向けのGNOME、GTKドキュメントです。
開発者向けドキュメント-ここでは、人々が実際にコア内部ロジックに貢献して、それを強化またはスケーリングすると想定しています。
3種類すべてのドキュメントを作成する必要性と方法は異なります。
エンドユーザーレベルのドキュメントは、コード内で実行することはできません。通常、これらはユーザーマニュアルのような外部ドキュメントです。コード内に含めることはできません（ソースコードのtar.gz内にある場合でも）。
APIドキュメントは、多くの場合、doxygenの種類のフレームワークを使用して実行できます（通常は最適に実行できます）。関数の上のコメントは、完全にフォーマットされたページに変換できます。このようにして、フォーマットの労力が節約され、一貫性が実現されますが、ドキュメントの主要な詳細は手書きのままです。また、APIが進化したり互換性がなくなったりした場合、コメントを変更すると新しいバージョンのドキュメントが簡単になることがわかります。私が見たもう一つのそのようなことは、それを使用する方法を説明する小さな「api_example.c」ファイルを書くことです。ほとんどの中規模プロジェクトでは、これで十分です。
最後になりますが、最も重要なのは、コードの内部動作を説明する設計ドキュメントです。言うのは難しいですが、これは専門的に支払われた会社でさえまれです。多くの企業は、コードの外のどこかに「設計ドキュメント」を作成することを好みますが、残念ながら、コードが進化するにつれて、これらはドキュメントから切り離されたままになります。このようなシナリオでは、コメントがたくさんあり、コメントの上にコメントがあると、実際にははるかに役立ちます。通常は[〜＃〜] not [〜＃〜]完全です-しかし、ほとんどの場合、開発者が十分に賢い場合、本当に重要なのは、すべての非自明な部分にたくさんコメントすることです。このアプローチは常にはるかにうまく機能します。
実際、これを念頭に置いてください-用語とより広範なビジネスロジックを説明するためだけに、より高いレベルのドキュメントを完全にドラフトし、詳細をコード内に説明したままにする必要があります（そしてコードとともに進化させます）。ほとんどの場合、外部ドキュメントは決してコードと同じくらい速く進化するので、依存関係と詳細に制限する必要があります。
ディパン。
OSSプロジェクトを成功させたい場合は、ユーザーに十分なドキュメントを提供する必要があります。ほとんどのOSSプロジェクトのユーザーベースは比較的小さく、コードを詳しく調べます。
何らかの方法でプロジェクトに直接貢献していない場合、ソースコードを見るのは、バグを発見したと感じ、自分で修正するか、見つけたバグをプロジェクトに通知したいときだけです。コードのどこに問題があると思いますか。
複雑なOSSプロジェクトを評価して、実質的なドキュメントがまったく見つからなかった回数はわかりません。別のより透明性の高い選択肢がある場合は、その使用方法を試行錯誤して何日も費やしたくないため、またはプロジェクトが「グリーン」または「あまりにも」であると感じたために、その方向に進むことがよくあります。素人っぽい」にコミットします。
私が使用したほぼすべての人気のあるJava OSSパッケージはjavadocsで十分に文書化されています。技術的には、これはソースコードに文書が含まれていることを意味します。
いずれにせよ、これらは一般的に私が使用した中で最も文書化されたシステムのいくつかです。これは、ドキュメントをソースコードと一緒に保持し、並行して更新できるようにするためだと思います。その後、ドキュメントを分割します。