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

目前我工作的文档有点混乱。几乎没有足够的文档，现有的文档分布在许多word文档中，因此很难找到任何内容

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

• 我的想法是，文档应以一系列短文（MSDN/Html帮助样式）的形式进行结构化，并以适当的树进行结构化：
  • 最好能够生成一个独立的Html帮助样式包，并随应用程序一起提供
  • 以及能够制作一个MSDN风格的网站作为那些懒得看CD的人的参考
  • 搜索当然是必不可少的
• 它需要至少相当容易更新-如果有一个17步的过程来更新已发布的文档，那么做简单的更改似乎需要做太多的工作，而且没有人会费心更新它
• 文档本质上是技术性的，因此理想情况下，能够包含从嵌入到C#代码中的Xml文档之类的东西生成的文档会很好。不过，这绝对是一个附带要求——目前，有用的Xml文档很少，只是我计划在将来解决这个问题
• 出于同样的原因，能够处理附件（代码示例等）通常是很好的。我并不期望有什么新奇的东西，但我需要记住这一点，以确保它至少不会处理得很糟糕

---

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

如果您使用，您可以在漂亮的PDF和打印副本中获得所有文档，并且能够生成html（通过）。TeX也具有纯文本的优势，因此您可以将其与您喜爱的版本控制系统可靠地跟踪/合并。

我们将其用作文档存储库。有公共和私有部分是相当容易的，并且有一个很好的所见即所得编辑器。它可以处理附件，如果你喜欢，可以保存为PDF文档。

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

我使用了它，效果很好。它是简单的html，但有一个生成过程，使所有内容看起来都是一致的。它可以与应用打包为.hlp文件，也可以发布到网站。看看吧，它很简单，这样你就可以重新开始你的工作：）

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

从DocBook源代码生成PDF、HTML和其他格式非常简单（有工具可用于此目的）。

我已经开始使用。这并不完全是我最初想要的（我想我真的是在寻找CMS），但它做得很好，而且在某些方面比我最初想的要好（特别是它是一个维基——我还没有把它发布给我们的客户，所以我不确定这会有多好）

我使用插件和模板在左边获得一个导航树，如果我发布wiki本身，我将使用允许用户发布反馈

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

我不确定“language”一词是否正确在标题中，是描述我所寻找的最好的词——如果有人能想出一个更好的词，那么请继续改变它。