您的团队使用哪些工具编写用户手册？

Question

基本要求是：

• 人类可读/文本格式（便于版本控制）
• 在线（用于协作）
• 简单格式化（降价确定，html太多）
• 严格格式化（因此作者不会发明新类型的标题， 子弹等。）
• 可导出为PDF，HTML
• 轻松备份和部署（因此我们可以“部署”到客户站点 只读版本）

我们正在考虑使用某种wiki引擎，但它需要使用文件进行存储，或者有其他方式“部署”给客户并且易于安装/维护。此外，它必须是免费/廉价的（汇合太昂贵）

有什么建议吗？

编辑：我不是在寻找用于记录代码的工具，我们使用Sandcastle进行了覆盖。

Answer 1

LaTeX

Answer 2

虽然它可能无法满足您的所有要求，但DokuWiki可能值得一看。

与其他wiki一样，它有一个simple syntax，版本控制为track revisions，生成table of contents和full-text search功能，可以方便地提供帮助系统

您可能需要评估feature list以确定它是否符合您的需求。

此外，似乎还有一个很好的collection of avaialble plugins。虽然我没有使用过DokuWiki或它的插件，但PDF export似乎也有可用的插件。

Answer 3

对于我们的API，我们使用Doxygen，这很棒。

Answer 4

Pandoc是一种用于在各种标记格式之间进行转换的出色工具。我们在markdown中编写文档并使用Pandoc转换为其他格式。

来自pandoc网站：

  

如果您需要从一个文件转换文件   标记格式到另一个，pandoc是   你的瑞士军刀。 Pandoc可以读取降价和   （子集）reStructuredText，   纺织品，HTML和LaTeX，它可以   写明文，降价，   reStructuredText，HTML，LaTeX，   ConTeXt，PDF，RTF，DocBook XML，   OpenDocument XML，ODT，GNU Texinfo，   MediaWiki标记，纺织品，groff man   页面，Emacs组织模式，EPUB电子书，   和S5和Slidy HTML幻灯片放映。 PDF   输出（通过LaTeX）也受支持   使用随附的markdown2pdf包装器   脚本。

Pandoc获得了开源的额外分数，并以Haskell的热度写出来;）

Answer 5

我不能说Asciidoc的好东西。它有一个非常简单的标记语法，可以生成从pdf到roff的所有内容，可移植到实现，并且非常容易插入到任何wiki中，只需进行一些小的更改。

即使在其标记状态下，它也非常非常容易阅读。我使用它时唯一需要摆弄的是桌子，但这并不太难。

如果您将文本格式的文件保存在存储库中，则修订跟踪非常简单。

对于代码文档，我使用doxygen。

Answer 6

您没有提到您正在使用的语言/框架。那里有非常好的文档工具，但其中一些特定于你正在开发的内容。我们是一个C＃商店，所以如果你使用.NET，我的答案只适用于你。

我们使用Sandcastle，它不仅是免费的，而且是开源的。虽然人们主要将其视为从XML文档生成文档的严格应用程序，但您可以在MAML中提供自己的内容。它可以针对CHM和网站部署，满足我们的需求。根据我的理解，还有一些其他工具可以提供标记收藏夹和主题评级等内容，但我们尚未开始使用它们。

这为我们提供了内部和外部文档。由于我们也使用Team Foundation Server，因此我们在Sharepoint的Team Project中使用内置Wiki，但这更适合项目协作。

编辑：修复了断开的链接，还想提一下我们使用的Sandcastle还有其他工具。 Sandcastle Help File Builder和GhostDoc等内容是常用工具。第一个编辑Sandcastle项目和MAML，第二个是改进代码中的评论质量。

Answer 7

试试Sphinx。所有python文档都是使用此工具http://docs.python.org/

创建的

Answer 8

我们使用help and manual作为手册和帮助文件。没有html导出，但它提供了html帮助，winhelp，pdf和更多格式。

Answer 9

我们正在使用维基。我推荐MoinMoin，因为

• 设置非常简单（即使在笔记本电脑上）
• 非常简单的备份（你甚至可以将wiki提交给版本控制系统，以便在笔记本电脑之间进行同步，以便离线使用）。
• 语法不错
• 易于扩展
• 易于搜索

我们没有使用像Word这样的东西：

• 文档腐烂太快
• 搜索所有文件很痛苦
• 信息位之间的链接很痛苦
• 版本之间没有差异
• 二进制格式扼杀了任何VCS
• 没有深刻的书签
• 文件变得太大，然后变得笨拙：拆分（不再搜索）或等待年龄加载。

Answer 10

对于“手册”，Docbook。它是为技术文档设计的SGML方言。 http://www.docbook.org/。它可能不符合您的“简单标记”标准，但它肯定会在LaTex中产生很好的输出（可以转换为PDF）和良好的HTML输出，如果你为它烹饪自己的CSS样式表。文本文件保留在版本控制中。所有程序还使用一个库，该库将命令行参数解析与“ - help”输出组合在一起（格式，手册页和docbook）。对于API参考，当然是doxygen。

Answer 11

在我目前的工作中，我们制作了一次性使用的软件，因此文档经常被放在一边，并在Word中完成。

然而，在我上一份工作中，文档团队似乎不断地咆哮和赞美mad cap software's product "Flare"。它允许您以一种格式书写并发布到多种媒体，因此您的手册也可以是您的在线帮助或网站等...

Answer 12

我们在DocToHelp取得了巨大成功。它适用于基于Microsoft Word的文档以及其他表单，甚至还为Visual Studio提供了一些出色的集成功能。

最好的部分是，一旦你有一个导入DocToHelp的核心文档库，你可以选择任何一种导出格式，包括WinHelp，HTML帮助，Java帮助或漂亮而精美的可搜索网络帮助。 / p>

Answer 13

对于我使用Doxygen的代码的文档。我更喜欢linux版本，我在Windows版本中遇到了一些问题

Answer 14

我的公司使用MediaWiki和TikiWiki来处理大多数文档。我们还有一个人可以将内容编译成MS Word和PDF格式，以便打印/发送给客户。我建议你像瘟疫一样避免TikiWiki。 MediaWiki非常棒，因为它非常易于使用，因为每个人都知道如何使用它 - 它是事实上的标准维基，当之无愧，恕我直言。

Answer 15

有一段时间我们使用DocBook，但很难扩展更高级和必要的功能（语法突出显示，分成几个文件，多语言管理等）。后来，我们决定从头开始编写自己的系统，并将其作为开源来源发布：link text。它使用纯文本文件和Markdown作为语法语言，现在我们拥有了所需的一切。缺点是目前可能没有Markdown解析器产生除HTML输出之外的其他东西。目前这已足够，但我们正在考虑很快实施PDF支持。

此外，我们正在维护MediaWiki作为基于社区的帮助。

Answer 16

我们使用Word。它被放入我们的版本控制中，所以我们有历史（有一个链接到每个项目的文档文件夹）。格式化可以使用我们现在设置的所有模板进行控制，因此在布局标准中可以轻松进行更改。文件可以导出为PDF。您可以将它们发布为只读文档，以便与用户共享。

Answer 17

尝试Dikiwiki