コードのドキュメントをどこに置くか？

私は現在、2つのシステムを使用してコードドキュメントを記述しています（C ++を使用しています）。

• Doxygen形式を使用して、メソッドとクラスメンバーに関するドキュメントがコードの横に追加されます。サーバーでは、Doxygenがソースで実行されるため、Webブラウザーで出力を確認できます。
• 概要ページ（クラスのセット、アプリケーションの構造、サンプルコードなど）がWikiに追加されます。

メンバーやクラスに関するドキュメントはコードに非常に近いため、このアプローチは簡単だと個人的に思いますが、概要ページはWikiで編集するのが非常に簡単です（また、画像、表などを追加するのも簡単です）。Webブラウザを使用すると、両方のドキュメントを表示できます。

私の同僚は、すべてをDoxygenに入れることを提案しています。これは、MicrosoftのHTML WorkShopまたはQt Assistantを使用して、すべてを含む1つの大きなヘルプファイルを作成できるためです。私の懸念は、特に表、画像などを追加する場合、Doxygenスタイルのドキュメントの編集がはるかに難しいことです（Wikiと比較して）（または、生成する必要のないDoxygenの「プレビュー」ツールがありますか？結果を見る前のコード？）

大きなオープンソース（またはクローズドソース）プロジェクトは、コードド​​キュメントを書くために何を使用しますか？彼らはこれをDoxygenスタイルとWikiに分けていますか？または、別のシステムを使用していますか？

ドキュメントを公開する最も適切な方法は何ですか？Webサーバー/ブラウザ経由、または大きな（数MBの）ヘルプファイル経由？

コードドキュメントを作成するとき、どのアプローチを取りますか？

すべてのドキュメントを2つではなく1つのシステムに置くことは、実際の利点となります。バックアップと復元、バージョニング、グローバル検索、グローバル検索と置換、クロスリンク、すべてのドキュメントを1つの最終ドキュメントに収めるなど、2つの異なるメンテナンスを行う必要がない場合、通常は「摩擦」が少ない重複する機能を持つシステム。

一方、これらの利点がWikiの使いやすさを上回るかどうかを考慮する必要があります。Wikiを使用すると、編集/生成/絞り込み編集/再生成の円が速くなる場合があります。概要ページを別のdoxygenサブプロジェクトとして保持することで、doxygenを使用すると、このサイクルを非常に高速に実行できると思います。doxygenの外部リンク機能を利用できます。これは、「クイックプレビュー」に代わるものではなく、もちろんその方向への一歩です。私はこれまで自分でこれをやったことはありませんが、自分のケースで機能するかどうか知りたい場合は、自分で試してみる必要があると思います。

他のプロジェクトに関して：私は、doxygenのようなツールは、主にライブラリのドキュメント用であると思います。サードパーティのライブラリベンダーではなく、ライブラリを使用する全員がソースコードに完全にアクセスできる場合、doxygenなどのツールの必要性は疑わしいです。たとえば、チームでは、エンドユーザードキュメントとデータベースモデルのドキュメントを除き、コード以外の外部ドキュメントはほとんどありません。ドキュメントのようなもののために私たちの主なツールはある のDocBookとFOP私たちに満足な結果を与えます、。

最初にコードドキュメントを使用します。可能であれば、Wikiと他のメソッドを追加します

それを維持するのは難しいでしょう。

実用的な答え：

実際には、開発者が最初に行うことは、コードをチェックすることです。

開発者として、Wiki、マニュアルなどの外部ドキュメントが欲しいです。しかし、私が最初に行うことは、コードをレビューすることです（他の開発者から、時には自分の開発者から）。

いくつかのプロジェクトと顧客で働いた開発者として、私は可能な限り外部のドキュメントを追加しますが、多くのワークロードがあり、wikiをサポートできませんでした。

プロジェクトマネージャーや他の上司がドキュメントを気にしない場合もあれば、開発者が気にしない場合もあります。

そして、私ができる最善のことは、コードにコメントを追加することです。

幸運を

他のシステムを使用するものもあります- たとえば、PythonのSphinxを見てください。すべてを構築するオールインワンのdocシステムがあります（C / C ++でも機能します）

ドキュメンテーションはコードとは別のものであると常に考えています。doxygenは素晴らしいのですが、それは「ドキュメント」ではなくAPIの概要のためです。そのためには、Wikiは優れていますが、主にPDFを生成して他の人（テスター、顧客など）に渡すことができるため、ASCIIDOCを使用してその結果をコードとともにソース管理に保存することを好みます

Doxygenを使用すると、PDF、HTML、Wikiページなど、考えられるほぼすべてを構築できます。

私の個人的な好みは、Doxygenとwikiの両方と、それらが分岐したときに確認するスクリプトまたは何かを持つことです。

バージョン1.8.0以降、doxygen はMarkdownをサポートします。これにより、Wikiシステムの場合と同様に静的ページの作成が便利になります。

対象読者

この質問に答えるとき、誰がこのドキュメントを読むつもりなのかを本当に尋ねる必要があると思います。開発者は、ユーザーまたはビジネスアナリストに対してもまったく異なるニーズを持っています。

• 開発者として：調査対象のコードに関連するドキュメント、インターフェイスコントラクトなどの詳細、および使用例。おそらくいくつかの高レベルのドキュメント、および適切な測定のためのプロトコル仕様。
• ユーザーとして：ヘルプメニューから入手できるドキュメント、またはソフトウェアの使用方法に関するアクセス可能なWebサイト。
• ビジネスアナリストとして：ドキュメントとして、またはアクセス可能なWebサイトとして利用可能なドキュメントが役立ちます。プロトコル、高レベルアーキテクチャ、およびユースケースについての控えめな詳細が最適です。

メンテナンス

このドキュメントのソースをどこに配置するかは、対象読者と、対象読者のために誰が書いているかに依存します。

• 開発者の家しかありませんか？コードにすべてを配置します。それが更新されることをお勧めします。ドキュメントの更新がコードの変更と同じくらい重要であることを奨励する文化に取り組む必要があります。
• 開発者とドキュメンテーションライターの家がありますか？責任を分割します。開発者向けの開発者向けツールを使用し、ドキュメント作成者用のドキュメント作成者ツールを使用します。

可能な場合は、コード例またはユースケースを実行できることを確認してください。実行を自動化し、内部的に障害にフラグを立てます。おそらく、これらのページは質の悪い、または悪いドキュメントです。

さらに、ドキュメントを記述するために選択するツールが何であれ、ドキュメントの特定のバージョンをコードの特定のバージョンに関連付けるための信頼できる手段が必要です。これは、単一の常緑展開のある幸せなクラウドランドでも有益です。

ドキュメントの統合

一部のドキュメントを作成するには統合が必要になる場合がありますが、必要なすべてのドキュメントにアクセスするための単一の場所をユーザーが期待することに注意してください。

ビジネスアナリストは、API仕様、設計仕様、および使用シナリオを個別のドキュメントまたはWebサイトの個別のセクションに配置することに非常に満足しています。

開発者はソースから見えるすべてのものを好みますが、いくつかの高レベルの設計ドキュメントと、コードの外部にある詳細なプロトコル仕様ドキュメントがあることは非常にうれしいですが、同じチェックアウト内であることが望ましいです。

あなたの場合

正直に言うと、Wikiのドキュメントは、おそらくコードベースのドキュメントと同じ種類ではありません。マージするのも意味がないかもしれません。

一方、2つの統合は、いくつかの簡単な方法で実現できます。

• ソースドキュメンテーションツール（doxygenなど）はhtmlを生成でき、wikiはWebサーバー上に存在します。Wikiと一緒にビルドバージョンを提供し、2つを相互リンクするだけの簡単な統合ポイントになります。
• 一部のウィキ製品では、コードベースにチェックインできるファイルからウィキを直接実行できます。これにより、ドキュメントをコードと組み合わせたまま、シンプルなwysiwygツールが提供されます。
• pdfなどの他の形式にも対応できますが、これは使用する特定のツールに依存します。wikiをマークダウンファイルにスクレイピングし、doxygen（または他のツール）経由でフィードすることは理にかなっているかもしれません。wikiとソースを個別にpdfにして、pdfマージツールを使用するのが理にかなっている場合があります。

1日の終わりに、どのドキュメントシステムのメンテナンスコストが低く、開発者、ビジネスアナリスト、ユーザーの視聴者に見られるような高品質の製品を提供するのに役立つかを把握してください。これらのグループのいずれかを妨げるものは、必然的に製品の品質を低下させます。

ASCIIを使用している場合は、ドキュメントデータをソースコードの上位ビットに保存する必要があります。そうすれば、最も賢い（読むに値する）ユーザーだけがドキュメントを使用できるようになります。

明確に定義された、簡単にエクスポート可能な移植可能な形式のドキュメントを作成することは、本当の利点かもしれません。もしスフィンクスが死ぬなら（ありそうにないが）他のシステムに変換するだけで、それはスクリプト可能なタスクだと思う。Wikiからデータを移動する（おそらく独自の形式でデータベースに保存するのは苦痛かもしれません）。