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

Question

目前，我工作的文档处于某种状态。几乎没有足够的文档，而且确实存在的文档分布在许多word文档中，因此很难找到任何东西。

我试图采取一些主动行动，并对其进行改进，我认为第一件事是找到一种更好的格式来编写文档：

• 我的想法是，文档应该在一系列短文(MSDN / Html样式)中进行结构化，并在一个合适的树( )中进行结构化。
  • 如果能够生成一个独立的Html-Help风格的包，并随应用程序一起提供，那就太好了。
  • 以及能够制作一个MSDN风格的网站，作为那些懒得看CD的参考。
  • 当然，搜索是必须的。

​

• 它至少需要相当容易地更新--如果有一个17步的过程来更新已发布的文档，那么它就会使做简单的更改看起来工作量太大了，而且没有人会费心去更新它。
• 文档本质上是技术性的，因此理想情况下，能够包含从嵌入在C#代码中的Xml文档之类的内容生成的文档将是很好的。然而，这绝对是一个附带的需求--目前很少有有用的Xml文档存在，只是在将来我计划修复它。
• 出于同样的原因，能够处理诸如附件(代码示例等)之类的事情通常是很好的。我没有期待任何花哨的东西，但这是我需要记住的东西，以确保它至少不会处理不好。

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

Answer 1

我已经开始使用DokuWiki了。这并不是我最初想要的(我想我真的是在寻找CMS)，但它确实做到了这一点，而且在某些方面比我最初想要的更好(特别是它是一个wiki --我还没有把它发布给我们的客户，所以我不知道这会有多好)。

我使用IndexMenu插件和北极模板来获得左边的导航树，如果我发布wiki本身，我将使用讨论插件来允许用户发布反馈。

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

Answer 2

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

Answer 3

如果您使用LaTeX，您可以获得您的所有文档的外观很好的PDF和打印副本，以及能够生成html (通过latex2html)。TeX的优点也是纯文本，所以您可以可靠地跟踪/合并它与您最喜欢的修订控制系统。