手工书写软件

Question

我试图找到一个软件来帮助一个小型的(~3-5人)团队编写一个用户指南和一个API参考软件的可扩展部分。我们非常喜欢使用某种形式的wiki，但是有一些特定的要求：

• 将手册导出为在线和离线可读表单的能力(例如，一组可以放在web服务器上或在本地读取的HTML文件)
• 从XML文档自动创建页面。我们是用VB.Net/C#..Net编写的，而且大多数API特定的内容已经有XML文档注释。如果手册的API部分能够指定类、方法、参数等，并且允许作者从其他人链接到这些页面，那就太好了。(例如，有一个详细说明foo类的页面，并且能够有一个页面详细说明如何使用foo.increaseBarCount()方法的API链接来完成一些常规任务)。

除了显而易见的(“易于使用”，“为我完成所有的写作，以便我能够摆脱编写技术文档的单调乏味”，“不会引发一场全球热核战争”)之外，这就差不多了。

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

Answer 1

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

关于一般文档，我们有使用wiki的良好经验。我们使用MediaWiki (维基百科的名声)，但是任何一个像样的wiki都可以。我们从来没有尝试过打印它，但是谷歌展示了各种从MediaWiki打印出来的解决方案，所以你很可能不需要太多的麻烦就能让一些东西工作起来。

我们喜欢在文档中使用wiki的主要原因是，当您检测到错误时，您可以很容易地更改它们；这会使它们保持新鲜。此外，不要担心有一个过时的副本。

Answer 2

你可以去看看亚特兰西安合流。我相信他们有一个免费的版本(可能只是一个出价，所以你可能最终会支付长期，不知道)的小团队。他们也有一个API，所以编写一个实用程序来提取XML文档并使用该C#创建页面并不太困难，如果已经不存在了。这个wiki很容易使用，并且被开源项目使用了很多。您可以查看ANTLR文档，它是Confluence，作为一个示例。