2

目前，我工作的文档处于某种状态。没有任何地方足够接近它，并且确实存在的文档分散在许多word文档中，因此很难找到任何东西。

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

  • 我的想法是，文档应该以一系列短文（MSDN / Html 帮助风格）的形式组织起来，并以合适的树形式组织起来：
    • 最好能够生成一个独立的 Html-Help 样式包以随应用程序一起提供
    • 以及能够制作一个 MSDN 风格的网站，作为那些懒得看 CD 的人的参考。
    • 搜索当然是必须的
  • 它至少需要相当容易更新——如果有一个 17 步的过程来更新已发布的文档，那么进行简单的更改就会显得工作量太大，而且没有人会费心去更新它。
  • 该文档本质上是技术性的，因此理想情况下，能够包含从嵌入在 C# 代码中的 Xml 文档等生成的文档会很好。然而，这绝对是一个附带要求——目前很少有有用的 Xml 文档存在，只是我计划在未来修复它。
  • 出于同样的原因，能够处理附件（代码示例等）之类的东西通常很好处理不好。

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

4

6 回答 6

1

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

于 2009-10-14T17:59:37.523 回答
0

我们使用汇合作为我们的文档存储库。拥有公共和私人部分相当容易，并且有一个很好的 WYSIWYG 编辑器。它可以处理附件，并且可以根据需要保存为 PDF 文档。

于 2009-10-14T17:59:35.900 回答
0

如果您使用LaTeX，您可以在精美的 PDF 和打印副本中获取所有文档，并且能够生成 html（通过latex2html）。TeX 也具有纯文本的优点，因此您可以使用您最喜欢的修订控制系统可靠地跟踪/合并它。

于 2009-10-14T17:53:42.737 回答
0

我使用robohelp 取得了很好的效果。它是纯 html，但有一个生成过程，可以保持一切看起来一致。它可以与应用程序一起打包为 .hlp 文件，或发布到网站。看看吧，它很简单，所以你可以回去做你的工作:)

于 2009-10-14T18:06:46.190 回答
0

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

从 DocBook 源代码生成 PDF、HTML 和其他格式很简单（为此目的存在工具）。

于 2009-10-14T18:14:02.487 回答
0

我已经开始使用DokuWiki了。它不完全是我最初想要的（我想我真的在寻找 CMS），但它完成了这项工作并且在某些方面它比我最初的想法更好（特别是它的维基 - 我还没有已将其发布给我们的客户，因此我不确定效果如何）

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

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

于 2009-10-20T15:47:27.270 回答