Wikiは、ソフトウェア開発用のドキュメントを保存するのに本当に適切ですか？
文書化されたソフトウェア開発が成功につながることは誰もが知っています。ただし、通常、UMLダイアグラムなど、プレーンテキストだけでなくバイナリコンテンツもドキュメントに含まれることを意味します。そして、私は多くの人がそう言うと聞いています。バージョン管理システムは、バイナリファイルの適切な場所ではありません。私はこの問題を完全に理解し、同意します。ドキュメントを保存するのに最適な場所は何人かの熟練した開発者に尋ねました。私が得た答えは「wiki」です。ウィキは良いですが、私は別の潜在的な問題を検討しました。バージョン管理システムに保存されているソースコードを、wiki内の関連ドキュメントに接続するにはどうすればよいですか？誰かがgitまたはMercurialのリポジトリのクローンを作成したとしましょう。どのようにして文書を簡単に見つけることができますか？または私はちょうど何かを逃したのですか？
一部のWikiシステムには、ソース管理システムと統合できる機能があることを知っています。しかし、私の懸念は統合の能力についてではありません。 gitリポジトリからソースコードのクローンを作成し、しばらくしてから電車に乗って、電車の中でオフラインで作業を続けたい場合（これはDVCSの大きな機能です）。その後、電車の中でオフラインで作業しているため、ドキュメントにアクセスできないことに突然気づきました。一方、ドキュメントがgitリポジトリに保存されている場合は、リポジトリが複製されたドキュメントにアクセスできます。
WIKIはソフトウェア開発用のドキュメントを保存するのに本当に適切ですか？
ドキュメント、PDF、その他の種類のファイルを作成する代わりに、コラボレーションツールとしてのWIKIの可能性を最大限に引き出してみませんか？そこにドキュメントを記述し、図を添付し、さらに優れたものにすることができます。 Fitnesse を使用すると、Wikiページを実行可能な仕様にすることができるので、実際に役立つ生きたドキュメントに変えることができます。
十分に文書化されたソフトウェア開発が成功につながることを誰もが知っています
これに気をつけて。ドキュメントはがらくたのコードを良いものに変えないので、成功につながりません。しかし、ドキュメントは成功するソフトウェアへの道の一部です。しかし、ほんの一部であり、彼らは優れた実践と優れた人々を置き換えることはありません。
複数の回答がTracを提案として指し示しているので、私は同様の提案をしたいと思いますが、私の意見ではより良い、代替案： Redmine 。
Redmineは、Wiki、ドキュメントリポジトリ、バージョン管理統合などのプロジェクト管理ソリューションです。また、Ruby on Railsで記述されており、私の経験ではTracよりも拡張およびハッキングがはるかに簡単です。
何よりも本当に使いやすく、チームがそれを使用するのは簡単です。
特徴：
- 複数のプロジェクトのサポート
- 柔軟な役割ベースのアクセス制御
- 柔軟な問題追跡システム
- ガントチャートとカレンダー
- ニュース、ドキュメント、ファイル管理
- フィードとメール通知
- プロジェクトごとのwiki
- プロジェクトごとのフォーラム
- 時間追跡
- 課題、時間入力、プロジェクト、ユーザーのカスタムフィールド
- SCM統合（SVN、CVS、Git、Mercurial、Bazaar、Darcs）
- メールによる課題作成
- 複数のLDAP認証のサポート
- ユーザー自己登録サポート
- 多言語サポート
- 複数のデータベースのサポート
オフラインのニーズのために、バージョン管理が設計ドキュメントで煩雑になるという考えは好きではありません。これを尋ねる理由は確かにありますが、実際にオフラインでデザインドキュメントにアクセスする必要がある頻度はどれくらいですか？たぶん、これは本当にありふれたケースです。
いくつかのwiki（例 Ikiwiki ）は、あなたが言及したように、Gitにデータを保存する機能を持っています。それを前提として、通常のソースリポジトリの下に Gitサブモジュール としてドキュメントをリンクできます。
上記の設定では、ソースをプルしてサブモジュールを更新すると、ドキュメントの最新のコピーがプルされます。オフラインでは、それぞれを自由に編集できます。ネットワークに戻ると、両方を使用している共有場所に戻すことができます。
この厄介な部分は、ドキュメントが更新されるたびに（Ikiwiki Webインターフェースを介してでも）、Gitソースリポジトリの対応するサブモジュールも更新する必要があることです。ただし、これは簡単に自動化できます。
ドキュメントをソースコードと同じリポジトリに保存することは理にかなっています。 Sphinx は私にとって良いオプションのようです。
- それは入力として reStructuredText ファイルを必要とします。これは編集と差分が簡単です
- ハイパーリンク出力（HTML、PDFなど）を生成します
- ソースコードを参照 （Python、C、C++、JavaScript）
Tracは、統合されたWikiおよび便利なレポート機能であるSubversionへのインターフェースを提供します。 http://trac.edgewall.org/
しかし、私はあなたがインストールしたスタックについて知りません。
私はオフライン作業に準拠しようとはしません。誰にとっても最も使いやすいリソースを使用します。たとえば、PHPコードを記述している場合、 PHPDocumentor で生成できるインラインドキュメントを使用することをお勧めします。どこにでも生成でき、- Tracのプラグイン 。その後、オンラインまたはオフにすると、ドキュメントにかなりすばやくアクセスできます。
重要なのは使いやすさです。維持するのが難しいと、苦しみ始めます。問題が発生し始めると、ドキュメントの品質が低下します。それが起こると、人々は不平を言い始め、それからすべてが下り坂になります。