1

我正在开发一个新库，并且我正在使用 XML 注释作为 API 文档以及运行良好的 SandCastle。

但我需要编写额外的文档，涵盖概念、整体架构、工作演示等、类图等。

我有两个选择：

  1. 使用一些 wiki 引擎并编写文档 wiki 样式。
  2. 使用似乎是为此目的的 MAML。

使用 wiki 似乎是安全的解决方案，因为有许多稳定、流行和免费的引擎可用，但 API 和概念文档不会齐头并进（交叉链接、外观等）。使用 MAML 意味着一个学习曲线，我不确定它有多成熟以及它的优点/缺点是什么。

您是否为此目的使用过 MAML/Wiki，您学到了什么？你会建议我什么？

4

1 回答 1

3

就个人而言，我喜欢使用 Wiki 工作的自由。此时，您有一些不错的选择来编辑 MAML

我不能对 DocProject 说太多（虽然它看起来不错）。现在，我正在使用 SHFB 将 API 文档和一些概念文档合并到 MAML 中。编辑很不错，足以满足我的需要。我能够轻松地在我的 API 和概念文档之间设置目录和链接。SandcastleStyles是一个很好的示例资源。

与所有事情一样，有一些重要的问题要问。

  • 您是否有任何要求以一个包裹运送您的文档？ 就我而言，我需要将所有东西都放在一个漂亮的编译包中。你不能用 Wiki 做到这一点，但你可以用 Sandcastle 做到这一点。
  • Are you going to be the only person updating the conceptual content? Most wikis have a really nice editor and an ability to quickly link between topics. The only tool you need to edit content is a browser, which might be a requirement for a less technically-savvy writer.
于 2009-11-10T23:04:20.220 回答