使用 MAML 进行库的概念文档[关闭]
-
21-09-2019 - |
题
我正在开发一个新库,并且使用 API 文档的 XML 注释以及 SandCastle,效果非常好。
但我需要编写额外的文档,其中涵盖概念、整体架构、工作演示等、类图等。
我有两个选择:
- 使用一些 wiki 引擎并编写 wiki 风格的文档。
- 使用 MAML 似乎就是为了这个目的。
使用 wiki 似乎是安全的解决方案,因为有许多稳定、流行和免费的引擎可用,但 API 和概念文档不会齐头并进(交叉链接、外观等)。使用 MAML 意味着一个学习曲线,我不确定它有多成熟以及它的优点/缺点是什么。
您是否为此目的使用了 MAML/Wiki?您学到了什么?你会建议我什么?
解决方案
就我个人而言,我喜欢使用 Wiki 工作的自由。此时,您有一些不错的编辑 MAML 的选择
我不能对 DocProject 说太多(尽管它看起来不错)。现在,我正在使用 SHFB 将 API 文档和一些概念文档合并到 MAML 中。编辑器很不错,足以满足我的需求。我能够轻松设置 API 和概念文档之间的目录和链接。一个很好的例子资源是 沙堡风格.
与所有事情一样,有一些重要的问题需要问。
- 您是否有将文档打包在一个包裹中运送的要求? 就我而言,我需要将所有内容都放在一个好的编译包中。你不能用 Wiki 做到这一点,但你可以用 Sandcastle 做到这一点。
- 您将是唯一更新概念内容的人吗? 大多数 wiki 都有一个非常好的编辑器,并且能够在主题之间快速链接。编辑内容所需的唯一工具是浏览器,这可能是技术不太精通的作家所需要的。
不隶属于 StackOverflow