需要选择合适的语言来编写文档

Question

目前我工作的文档处于某种状态。没有足够的它，并且存在的文档分散在许多word文档中，使得很难找到任何东西。

我正在尝试采取一些措施并对其进行改进，我认为首先要找到一种更好的格式来编写文档：

• 我的想法是文档应该由一系列简短的文章（MSDN / Html帮助样式）构成，并在合适的树中构建：
  • 最好能够生成随应用程序一起提供的独立Html-Help样式包
  • 除了能够制作一个MSDN风格的网站，作为那些懒得看CD的人的参考。
  • 搜索当然是必须的
• 它需要至少相当容易更新 - 如果有一个17步骤的过程来更新已发布的文档，那么它使得做简单的更改似乎太多工作，并且没有人会费心去更新它。
• 文档本质上是技术性的，因此理想情况下能够包含嵌入在C＃代码中的Xml文档等生成的文档会很好。然而，这绝对是一个侧面要求 - 目前非常有用的Xml文档存在，它只是在未来我打算修复它。
• 出于同样的原因，能够处理附件（代码示例等等）之类的东西通常都很好。我不期待任何花哨的东西，但这是我需要牢记的事情，以确保它的至少没有处理得太厉害。

是否有适合此类文档的项目或语言？

Answer 1

我在C和C ++项目中使用doxygen获得了很好的效果，尽管它也支持许多其他语言。您将文档放在代码中的注释中，这些代码可以是简单或复杂的HTML标记。它很容易更新，因为它是代码的一部分。您可以将构建文档作为构建过程的一部分。不严格与API相关的其他主题可以作为单独的HTML文档添加。我使用的版本不支持搜索，因此您必须添加其他产品才能搜索这些页面。因为它是HTML，您可以添加代码示例，图表等。

Answer 2

如果您使用LaTeX，您可以获得外观精美的PDF和打印副本的所有文档，以及能够生成HTML（通过latex2html）。 TeX的优点还在于所有纯文本，因此您可以使用您喜欢的版本控制系统可靠地跟踪/合并它。

Answer 3

我们使用confluence作为我们的文档存储库。公共和私人部分相当容易，并且有一个很好的WYSIWYG编辑器。它可以处理附件，如果您愿意，可以将其保存为PDF文档。

Answer 4

我使用robohelp效果很好。它是普通的HTML，但有一个生成过程，保持外观一致。它可以与应用程序打包为.hlp文件，也可以发布到网站上。检查出来，这很简单，所以你可以回去做你的工作：）

Answer 5

干净的方法是使用DocBook。这很容易写和不正确。它也很容易解析，因为XML解析器是标准的，其他形式的文档（例如来自注释中的嵌入式文档）可以很容易地转换为这种格式。

直接从DocBook源生成PDF，HTML和其他格式（为此目的存在工具）。

Answer 6

我已经开始使用DokuWiki了。它不完全是我最初想要的（我认为我真的在寻找一个CMS），但它确实起到了作用，有些人认为它比我原来的想法更好（特别是它的维基 - 我还没有到目前为止我们已经向客户发布了这些信息，所以我不确定这会有多好用。）

我正在使用IndexMenu插件和Arctic模板来获取左侧的导航树，如果我发布了wiki本身，我将使用discussion plugin来允许用户发布反馈。

目前处理生成内容的方法是使用xslt模板生成dokuwiki语法，并将该输出直接写入“data / pages”文件夹中的文件/文件夹。