2

小規模な (~3-5 人) チームが A) ユーザー ガイドと B) ソフトウェアの拡張可能な部分の API リファレンスを作成するのに役立つソフトウェアを見つけようとしています。何らかの形式の Wiki を使用するというアイデアは非常に気に入っていますが、いくつかの特定の要件があります。

  • マニュアルをオンラインとオフラインの両方で読み取り可能な形式にエクスポートする機能(たとえば、Web サーバーに配置したり、ローカルで読み取ったりできる一連の HTML ファイル)

  • XML ドキュメントからページを自動的に作成します。私たちは VB.Net/C#.Net で書いていますが、API 固有のもののほとんどには既に XML ドキュメント コメントがあります。マニュアルの API 部分がクラス、メソッド、引数などを指定できれば素晴らしいことですが、ライターが他のページからこれらのページにリンクできるようにすることもできます。(たとえば、fooクラスの詳細を示すページを作成し、メソッドのページへの API リンクを使用して一般的なタスクを実行する方法を詳細に説明するページを作成できますfoo.increaseBarCount())。

明らかなことを除いて、それだけです（「使いやすい」、「技術文書を書くという退屈な作業から抜け出すことができるように、すべての執筆を行ってください」、「世界的な熱核戦争を引き起こさない」）。

そのようなソフトウェアは存在しますか？mediawiki 拡張機能を使用して、同様のシステムを組み合わせることはできますか?

4

2 に答える 2

1

「XMLドキュメントからページを自動的に作成する」に関しては、明らかな解決策はdoxygenです。ソース コードに埋め込まれた特別なドキュメント コメントからドキュメント (HTML、PDF、WinHelp ...) を作成します。Javadoc コメント、Qt スタイルのコメント、および XML コメントを処理します。HTML を生成すると、ページ名が予測できるので、簡単にリンクできます。doxygen は内部リンクを自動的に作成することもできます。他の形式を使用している場合は、ページ名を参照するために何らかのアンカーを埋め込むことができますが、それについてはよくわかりません。

一般的なドキュメントに関しては、wiki を使用して良い経験を積んでいます。私たちは (ウィキペディアで有名な) MediaWikiを使用していますが、まともなウィキなら何でもよいでしょう。私たちはそれを印刷しようとしたことはありませんが、Google は MediaWiki から印刷するためのさまざまなソリューションを示しているので、おそらくそれほど手間をかけずに何かを機能させることができます。

ドキュメントに wiki を使用することについて私たちが気に入っている主な点は、間違いを見つけたときに簡単に変更できることです。それはそれらを新鮮に保ちます。また、コピーが古いという心配もありません。

于 2011-03-01T08:55:04.087 に答える
0

AtlassianConfluenceをチェックできます。私は彼らが小さなチームのために無料版（おそらくただのオファーなので、長期的には支払うことになるかもしれません）を持っていると信じています。また、APIも備えているため、XML C＃ドキュメントを抽出し、APIを使用してそこからページを作成するユーティリティを作成するのはそれほど難しくありません（まだ存在しない場合）。wikiは使いやすく、オープンソースプロジェクトでかなり使用されています。例として、ConfluenceであるANTLRドキュメントを見ることができます。

于 2011-03-01T08:47:32.627 に答える