ライブラリの概念ドキュメントにMAMLを使用[閉じた

Question

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

しかし、概念、全体的なアーキテクチャ、作業デモなどをカバーする追加のドキュメントを作成する必要があります。

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

1. Wikiエンジンを使用して、ドキュメントを書きます。
2. この目的のためのMAMLを使用してください。

Wikiを使用すると、安定した人気のある無料のエンジンがたくさんありますが、APIや概念的なドキュメントは手をつないでいないため、安全なソリューションのようです（架橋、外観など）。 MAMLを使用することは学習曲線を意味し、それがどれほど成熟していて、その利点/短所が何であるかについてはわかりません。

この目的のためにMAML/Wikiを使用しましたか、そしてあなたの学習は何でしたか？何を提案しますか？

Answer 1

個人的には、私はウィキで働く自由が大好きです。この時点で、MAMLを編集するためのいくつかの適切な選択肢があります

• ドックプロジェクト
• サンドキャッスルヘルプファイルビルダー

私はドックプロジェクトにあまり話すことはできません（見た目はいいですが）。現在、SHFBを使用してAPIドキュメントといくつかの概念的なドキュメントをMAMLにマージしています。編集者はまともであり、私のニーズのために十分です。目次を簡単に設定し、APIと概念ドキュメント間にリンクすることができます。例を見るのに適したリソースはそうです SandCastLestyles.

すべてのことと同様に、尋ねるべきいくつかの重要な質問があります。

• ドキュメントを1つのパッケージに出荷する要件はありますか？ 私の場合、すべてを1つの素敵なコンパイルされたパッケージに出荷する必要がありました。 Wikiでそれをすることはできませんが、Sandcastleでそれを行うことができます。
• あなたは概念的なコンテンツを更新する唯一の人になるつもりですか？ ほとんどのWikiには、本当に素晴らしい編集者があり、トピック間をすばやくリンクする能力があります。コンテンツを編集するために必要な唯一のツールはブラウザです。これは、技術的ではないライターの要件かもしれません。