documentation - 您的团队使用什么工具来编写用户手册？

Question

基本要求是：

人类可读/文本格式（便于版本控制）
在线（用于协作）
轻松格式化（markdown ok，html 太多了）
严格的格式（所以作者不会发明新类型的标题、项目符号等）
可导出为 PDF、HTML
轻松备份和部署（因此我们可以作为只读版本“部署”到客户站点）

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

有什么建议么？

编辑：我不是在寻找记录代码的工具，我们已经使用 Sandcastle 进行了介绍。

score 18 · Accepted Answer

18

乳胶

于 2008-11-24T14:02:28.183 回答

score 8 · Accepted Answer

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

与其他 wiki 一样，它具有简单的语法、版本控制以跟踪修订、生成目录和全文搜索功能，这对于帮助系统来说非常方便。

您可能需要评估功能列表，看看它是否能满足您的需求。

此外，似乎也有很好的可用插件集合。虽然我没有使用过 DokuWiki 或其插件，但似乎也有可用于PDF 导出的插件。

score 7 · Accepted Answer

7

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

于 2008-11-24T13:52:12.870 回答

score 5 · Accepted Answer

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

从 pandoc 网站：

如果您需要将文件从一种标记格式转换为另一种标记格式，pandoc 就是您的瑞士军刀。Pandoc 可以读取 markdown 和（子集）reStructuredText、textile、HTML 和 LaTeX，它可以编写纯文本、markdown、reStructuredText、HTML、LaTeX、ConTeXt、PDF、RTF、DocBook XML、OpenDocument XML、ODT、GNU Texinfo、 MediaWiki 标记、纺织品、groff 手册页、Emacs 组织模式、EPUB 电子书以及 S5 和 Slidy HTML 幻灯片放映。包含的 markdown2pdf 包装脚本也支持 PDF 输出（通过 LaTeX）。

Pandoc 因开源并以 Haskell 的热度编写而获得加分；）

score 4 · Accepted Answer

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

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

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

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

score 3 · Accepted Answer

我们将帮助和手册用于手册和帮助文件。没有html导出，但是提供了html帮助、winhelp、pdf等格式。

score 2 · Accepted Answer

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

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

我们没有使用 Word 之类的东西，因为：

文档腐烂太快
搜索所有文档很痛苦
信息位之间的链接是一种痛苦
版本之间没有差异
让任何 VCS 都崩溃的二进制格式
没有深度书签
文档变得太大，然后变得笨拙：拆分（不再搜索）或等待很长时间才能加载。

score 2 · Accepted Answer

您没有提及您正在使用的语言/框架。那里有非常好的文档工具，但其中一些特定于您正在开发的内容。我们是一家 C# 商店，所以我的回答仅适用于您使用 .NET 的情况。

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

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

编辑：修复了断开的链接，并且还想提一下我们使用的与 Sandcastle 结合使用的其他工具。Sandcastle Help File Builder和GhostDoc等都是常用工具。第一个是编辑 Sandcastle 项目和 MAML，第二个是提高代码中的注释质量。

score 2 · Accepted Answer

2

试试狮身人面像。所有 python 文档都是使用这个工具制作的http://docs.python.org/

于 2011-06-28T10:23:19.227 回答

score 1 · Accepted Answer

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

score 1 · Accepted Answer

在我目前的工作中，我们大量生产一次性软件，因此文档经常被放在一边，并在 Word 中完成。

然而，在我的上一份工作中，文档团队似乎不断地对mad cap software 的产品“Flare”大肆咆哮。它允许您以一种格式编写并发布到多种媒体，因此您的手册也可以是您的在线帮助或网站等...

score 0 · Accepted Answer

0

试试Dikiwiki

于 2008-11-24T13:36:45.473 回答

score 0 · Accepted Answer

我们使用 Word。它被放入我们的版本控制中，所以我们有历史记录（每个项目都有一个文档文件夹）。格式可以使用模板进行控制，我们现在已经设置了所有这些模板，因此在布局标准内进行更改很容易。文件可以导出为 PDF。您可以将它们发布为只读文档以与用户共享。

score 0 · Accepted Answer

我们在DocToHelp方面取得了巨大成功。它适用于基于 Microsoft Word 的文档以及其他形式，它甚至为 Visual Studio 提供了一些很棒的集成功能。

最好的部分是一旦您将核心文档库导入 DocToHelp，您可以选择多种导出格式中的任何一种，无论是 WinHelp、HTML 帮助、Java 帮助还是漂亮而精美的可搜索网络帮助。

score 0 · Accepted Answer

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

score 0 · Accepted Answer

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

score 0 · Accepted Answer

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

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

documentation - 您的团队使用什么工具来编写用户手册？

17 回答 17

Related

Reference