协作手动写作软件[关闭]

Question

我正在尝试寻找一款软件来帮助一个小型（约 3-5 人）团队编写 A）用户指南和 B）软件可扩展部分的 API 参考。我们非常喜欢使用某种形式的 wiki 的想法，但有一些具体要求：

• 能够将手册导出为在线和离线可读形式（例如，可以放在网络服务器上或本地读取的一堆 HTML 文件）

• 从 XML 文档自动创建页面。我们使用 VB.Net/C#.Net 编写，大多数 API 特定的东西已经有 XML 文档 cmets。如果手册的 API 部分可以指定类、方法、参数等，而且还允许作者从其他人链接到这些页面，那就太好了。 （例如，有一个详细说明foo 类的页面，并且能够有一个详细说明如何使用指向foo.increaseBarCount() 方法页面的API 链接执行一些一般任务的页面） .

仅此而已，除了显而易见的（'易于使用'，'为我完成所有写作，这样我就可以摆脱编写技术文档的乏味'，'不会引发全球热核战争'） .

这样的软件存在吗？可以使用 mediawiki 扩展拼凑类似的系统吗？

Answer 1

至于“从 XML 文档自动创建页面”，显而易见的解决方案是 doxygen。它从源代码中嵌入的特殊文档 cmets 创建文档（HTML、PDF、WinHelp ...）。它处理 Javadoc cmets、Qt 样式 cmets 和 XML cmets。如果您生成 HTML，则页面名称是可预测的，因此很容易链接到； doxygen 还可以自动创建内部链接。如果您使用其他格式，您可能可以嵌入某种锚来引用页面名称，但我不太确定。

关于一般文档，我们在使用 wiki 方面有很好的经验。我们使用MediaWiki（维基百科的名气），但任何体面的维基都可能会这样做。 我们从未尝试过打印它，但 Google 展示了来自 MediaWiki 的各种打印解决方案，因此您可以轻松完成某些工作。

我们喜欢将 wiki 用于文档的主要好处是，当您发现错误时，您可以轻松地更改它们；让他们保持新鲜。另外，不用担心副本过时。

Answer 2

您可以查看 Atlassian Confluence。我相信他们为小型团队提供免费版本（可能只是一个报价，所以从长远来看你可能最终会付费，不知道）。他们也有一个 API，所以如果什么都不存在的话，编写一个实用程序来提取 XML C# 文档并使用 API 从它创建页面并不难。 wiki 易于使用，并且被开源项目大量使用。你可以看看 ANTLR Documentation，例如 Confluence。