コードドキュメントをどこに置くか？
現在、2つのシステムを使用してコードドキュメントを記述しています（C++を使用しています）。
- メソッドとクラスメンバーに関するドキュメントは、Doxygen形式を使用してコードの横に追加されます。サーバー上でDoxygenがソースで実行されるため、Webブラウザーで出力を確認できます
- 概要ページ（一連のクラス、アプリケーションの構造、サンプルコードなどを記述）がWikiに追加されます。
個人的には、メンバーとクラスに関するドキュメンテーションがコードに非常に近いため、このアプローチは簡単であると思います。一方、概要ページはWikiで非常に簡単に編集できます（また、画像、表などを追加するのも簡単です）。 Webブラウザを使用すると、両方のドキュメントを表示できます。
私の同僚は、すべてをDoxygenに入れることを提案しています。これは、すべてを含む1つの大きなヘルプファイルを作成できるためです（MicrosoftのHTML WorkShopまたはQt Assistantを使用します）。私の懸念は、特にWikiと比較して、Doxygenスタイルのドキュメントの編集がはるかに難しいことです（特に、テーブル、イメージなどを追加する場合）（または、生成する必要のないDoxygenの「プレビュー」ツールがあります）結果を見る前のコード？）
大きなオープンソース（またはクローズドソース）プロジェクトは、コードドキュメントの記述に何を使用していますか？彼らはまた、これをDoxygenスタイルとWikiの間で分割していますか？または、別のシステムを使用していますか？
ドキュメントを公開する最も適切な方法は何ですか？ Webサーバー/ブラウザを介して、または大きな（数百MB）ヘルプファイルを介して？
コードドキュメンテーションを作成するとき、どのアプローチを採用しますか？
すべてのドキュメントを2つではなく1つシステムで持つことは、実際の利点です。バックアップと復元、バージョン管理、グローバル検索、グローバル検索と置換、相互リンク、およびすべてのドキュメントを1つの最終ドキュメントにまとめると、通常、2つの異なるものを維持する必要がない場合に、「摩擦」が少なくなります。重複する機能を持つシステム。
一方で、これらの利点がWikiの使いやすさを上回るかどうかを考える必要があります。 edit/generate/refine edit/generate againサークルは、Wikiの方が速い場合があります。私はあなたが概要ページを別のdoxygenサブプロジェクトとして保持しているdoxygenでそのサイクルを非常に速く得ることができると思います。もちろん、doxygenの外部リンク機能を利用できます。これは、もちろん「クイックプレビュー」の代わりではありませんが、その方向。今のところ、私はこれを自分で行ったわけではありませんが、自分のケースで機能するかどうかを確認したい場合は、自分で試してみる必要があります。
他のプロジェクトに関して：doxygenのようなツールは主にライブラリのドキュメント化のためのものだと思います。サードパーティのライブラリベンダーではなく、ライブラリを使用するすべてのユーザーがソースコードに完全にアクセスできる場合、doxygenのようなツールが必要かどうかは疑問です。たとえば、私たちのチームでは、エンドユーザードキュメントとデータベースモデルのドキュメントを除いて、コードの外部に外部ドキュメントはほとんどありません。この種のドキュメントの主なツールは docbook および fop であり、満足のいく結果が得られます。
最初にコードドキュメントを使用してください。可能な場合はWikiと他のメソッドを追加してください
それを維持するのは難しいでしょう。
実用的な答え：
実際には、開発者が最初に行うことは、コードをチェックすることです。
開発者として、私はWiki（s）やマニュアルなどの外部ドキュメントを用意するのが好きです。しかし、私が最初に行うことは、コードをレビューすることです（時には他の開発者から、時には私自身）。
いくつかのプロジェクトや顧客で働いていた開発者として、私はできる限り外部のドキュメントを追加しますが、多くのワークロードがあり、wikiをサポートできなかったのはよくあることです。
場合によっては、プロジェクトマネージャーやその他の上司がドキュメントを気にしないこともあれば、他の開発者が気にしないこともあります。
そして、私ができる最善のことは、コードにコメントを追加することです。
幸運を
一部の人は他のシステムを使用しています。たとえば、Pythonの Sphinx を見てください。すべてを構築するオールインワンのドキュメントシステムがあります（C/C++でも機能します）。
ドキュメンテーションはコードとは別のものだといつも思っています。doxygenは素晴らしいですが、それは「ドキュメント」ではなく、APIの概要のためのものです。そのため、wikiは素晴らしいですが、主に以下を生成できるため、 [〜＃〜] asciidoc [〜＃〜] を使用し、その結果をコードとともにソース管理に保存することを好みますそこから他の人（例：テスター、顧客など）に渡すPDF
Doxygenを使用すると、PDF、HTML、Wikiページなど、考えられるほとんどすべてのものを構築できます。
私の個人的な好みは、Doxygenとwikiの両方と、分岐したときにチェックするスクリプトまたは何かを用意することです。
バージョン1.8.0以降、doxygen Markdownをサポート 。これにより、Wikiページの場合と同様に、静的ページを作成するエクスペリエンスが同様に便利になります。
対象読者
この質問に答えるとき、あなたは本当にこのドキュメントを読むつもりなのかを尋ねる必要があると思います。開発者は、ユーザーやビジネスアナリストにとっても、まったく異なるニーズを持っています。
- 開発者として：調査中のコードに関連するドキュメント、インターフェイスコントラクトなどの詳細、および使用例。おそらく、いくつかの高レベルのドキュメント、および適切な測定のためのプロトコル仕様。
- ユーザーとして：ヘルプメニューから入手できるドキュメント、またはソフトウェアの使用方法に関するアクセス可能なWebサイト。
- ビジネスアナリストとして：ドキュメントとして、またはアクセス可能なWebサイトとして利用できるドキュメントは有用です。プロトコル、高レベルのアーキテクチャ、および使用例については、適度な量の詳細が最適です。
メンテナンス
このドキュメントのソースをどこに配置するかは、対象ユーザー、および対象ユーザーのために誰が作成しているかによって異なります。
- 開発者の家しかありませんか？すべてをコードに配置します。それは更新されることを奨励します。ドキュメントの更新がコードの変更と同じくらい重要であることを奨励する文化に取り組む必要があります。
- 開発者とドキュメントライターの家をお持ちですか？責任を分割します。開発者向けの開発者向けツールを使用し、ドキュメント作成者向けのドキュメント作成者ツールを使用します。
可能な場合は、コード例またはユースケースを実行できることを確認してください。それらの実行を自動化し、内部的に障害にフラグを立てます。これらのページが不十分または悪いドキュメントである可能性があります。
さらに、ドキュメントの作成にどのツールを選択する場合でも、特定のバージョンのドキュメントを特定のバージョンのコードに関連付ける信頼できる手段が必要です。これは、単一の常緑樹配置のハッピークラウドランドでも、依然として有益です。
ドキュメントの統合
一部のドキュメントを作成するには統合が必要な場合がありますが、必要なすべてのドキュメントにアクセスできるのは1つの場所だけであることをユーザーだけが期待していることに注意してください。
ビジネスアナリストは、API仕様、設計仕様、および使用シナリオを別のドキュメントまたはWebサイトの別のセクションに配置することに非常に満足しています。
開発者はソースから見えるすべてのものを好みますが、いくつかの高レベルの設計ドキュメントと、コードの外部にある詳細なプロトコル仕様ドキュメントを持っていることを非常に嬉しく思いますが、できれば同じチェックアウト内にあります。
あなたのケース
正直に言うと、wikiのドキュメントは、コードベースのドキュメントと同じ種類ではないでしょう。マージすることも意味がないかもしれません。
一方、2つを統合するには、いくつかの簡単な方法があります。
- ソースドキュメントツール（doxygenなど）はhtmlを生成でき、wikiはWebサーバー上にあります。構築されたバージョンをwikiと一緒に提供し、2つを相互リンクすることは、単純な統合ポイントになります。
- 一部のWiki製品では、コードベースにチェックインできるファイルから直接Wikiを実行できます。これにより、ドキュメントとコードのペアを維持しながら、シンプルなwysiwygツールが提供されます。
- PDFなどの他の形式にも対応できますが、これは使用する特定のツールに依存します。 Wikiをマークダウンファイルにスクレイピングし、doxygen（または他のツール）を介してフィードすることは理にかなっています。 wikiとソースを別々にPDF化し、PDFマージツールを使用することは理にかなっています。
1日の終わりに、メンテナンスコストが低いドキュメントシステムを見つけ出し、開発者、ビジネスアナリスト、およびユーザーの視聴者から見て高品質の製品を提供するのに役立ちます。これらのグループのいずれかを妨げるものは、必然的に製品の品質を低下させます。
ASCIIを使用している場合は、非表示のドキュメントデータをソースコードの上位ビットに格納する必要があります。そうすれば、最も賢い（読むに値する）ユーザーだけがドキュメントを使用する機会を得られます。
明確に定義された、簡単にエクスポートできる移植可能な形式のドキュメントがあることは、本当の利点かもしれません。 sphinx が死んだ場合（可能性は低いですが）、他のシステムに変換するだけで、スクリプト可能なタスクになると思います。 wikiからデータを移動する（おそらく、独自の形式でデータベースに格納されるのは難しいかもしれません）。