1

私は新しいライブラリに取り組んでおり、非常にうまく機能する SandCastle と共に API ドキュメントに XML コメントを使用しています。

しかし、概念、全体的なアーキテクチャ、動作するデモなど、クラス図などをカバーする追加のドキュメントを書く必要があります.

2 つのオプションがあります。

  1. ウィキ エンジンを使用して、ドキュメンテーションをウィキ スタイルで記述します。
  2. この目的のためと思われる MAML を使用します。

wiki を使用することは安全な解決策に思えます。なぜなら、利用可能な安定した人気のある無料のエンジンがたくさんあるからです。ただし、API と概念的なドキュメントは連携しません (クロスリンク、外観など)。MAML を使用することは学習曲線を意味し、それがどの程度成熟しているか、およびその利点/欠点は何かについてはわかりません。

この目的で MAML/Wiki を使用したことがありますか?また、何を学んだのでしょうか? あなたは私に何を提案しますか?

4

1 に答える 1

3

個人的には、Wikiを使って自由に作業できることが大好きです。この時点で、MAMLを編集するための適切な選択肢がいくつかあります。

DocProjectとはあまり話せません（見た目はいいですが）。現在、SHFBを使用してAPIドキュメントといくつかの概念ドキュメントをMAMLにマージしています。エディターはまともで、私のニーズには十分すぎるほどです。目次を簡単に設定し、APIと概念ドキュメントをリンクすることができます。例を探すのに適したリソースはSandcastleStylesです。

すべてのものと同様に、いくつかの重要な質問があります。

  • ドキュメントを1つのパッケージで発送するための要件はありますか？ 私の場合、すべてを1つの優れたコンパイル済みパッケージで出荷する必要がありました。Wikiを使用してそれを行うことはできませんが、Sandcastleを使用してそれを行うことはできます。
  • コンセプトコンテンツを更新するのはあなただけですか？ ほとんどのウィキには、非常に優れたエディターとトピック間をすばやくリンクする機能があります。コンテンツを編集するために必要な唯一のツールはブラウザです。これは、技術に精通していないライターの要件となる可能性があります。
于 2009-11-10T23:04:20.220 に答える