使用 MAML 进行库的概念文档[关闭]

Question

我正在开发一个新库，并且使用 API 文档的 XML 注释以及 SandCastle，效果非常好。

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

我有两个选择：

1. 使用一些 wiki 引擎并编写 wiki 风格的文档。
2. 使用 MAML 似乎就是为了这个目的。

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

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

Answer 1

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

• 文档项目
• Sandcastle 帮助文件生成器

我不能对 DocProject 说太多（尽管它看起来不错）。现在，我正在使用 SHFB 将 API 文档和一些概念文档合并到 MAML 中。编辑器很不错，足以满足我的需求。我能够轻松设置 API 和概念文档之间的目录和链接。一个很好的例子资源是 沙堡风格.

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

• 您是否有将文档打包在一个包裹中运送的要求？ 就我而言，我需要将所有内容都放在一个好的编译包中。你不能用 Wiki 做到这一点，但你可以用 Sandcastle 做到这一点。
• 您将是唯一更新概念内容的人吗？ 大多数 wiki 都有一个非常好的编辑器，并且能够在主题之间快速链接。编辑内容所需的唯一工具是浏览器，这可能是技术不太精通的作家所需要的。