什么是编写用户手册（帮助文件）的好工具，它与版本控制集成

Question

编写用户手册的人不一定是程序员，他们需要一个可视化编辑器。一个主要问题是创作工具的内部格式;它应该是可读的text / html，因此很容易比较检查到版本控制的各个页面的版本。

Answer 1

的DocBook

_{（来源：docbook.org）}

Answer 2

Microsoft HTML Help Workshop可用于创建高质量的专业CHM帮助文件。您只需要一堆HTML文件。该工具将所有这些和捆绑包“编译”到一个帮助文件中。 可以使用Microsoft Word / Frontpage甚至Dreamweaver生成HTML文件。您可能需要考虑控制这些HTML文件的源。

Answer 3

Latex。 Lyx提供WYSIWYM用于编写乳胶文件。

Answer 4

在我以前的工作中，他们使用了名为flare的疯狂软件工具。

它似乎工作得很好。

Answer 5

还有其他专业产品允许帮助文件编写，他们支持“上下文ID”，这使得上下文敏感的帮助成为可能。 Doc To Help和RoboHelp是这类产品。

Answer 6

要考虑的好组合是Subversion，DocBook和Publican。

• 版本控制= Subversion
• 内容创作= DocBook
• 发布= Publican
• 可选WYSIWYG = Serna

目前，这是世界上最大的开源解决方案提供商使用的工具链之一，也是世界上大部分基于Linux的操作系统在企业市场中使用的名称。大多数（并且接近所有）Red Hat的官方文档都是以这种方式创建的。 Fedora也是如此。

这里的主要“专业人士”是这些是免费提供的工具，在技术作家市场上有很大的重叠。所有这些都能够（但可能不想）用XML编写，而挑选DocBook就像在90年代拿起HTML一样。 Subversion是一种非常常见的版本控制工具，像DocBook一样相对容易实现和使用。 Publican是一个很棒的发布工具，它可以使用DocBook XML，并将其发布为PDF，HTML，HTML-single等。显然，你的作者可以使用像Serna这样的WYSIWYG，但我在Geany（在Fedora上）或TextMate上使用片段（在OS X）个人。

主要的“骗局”是对技术性的看法。您的作者可能想要所见即所得（并且可以拥有它），并且根据您的文档需求，这可能是您最终使用的内容。正如您所知，那里有专门修复Microsoft Word样式（和标记）的“技术作家”的市场，因此将“创作”与“发布”分开的论据是基于已证实但不同的组织用例。要求文件必须符合工程/编程/源生产的相同标准。

您将获得的一些极端建议来自那些已经接触过XML文档价值的人和公司，特别是DITA领域的那些，其中某些跨国公司在受到影响的收购中享有盛誉。产品知识的格式和可用性。还有一些论点认为将文档锁定为“粘性”或封闭格式无助于未来的维护要求。这是开源选项在公司层面获得支持的地方。另外，显然，它是免费的。

Answer 7

您可以使用Subversion和MGTEK Help Producer。帮助生产者从Word文档中生成帮助文件。 TortoiseSVN附带了用于比较Word文档的不同修订版本的脚本（Word有一个版本比较工具）。

您的用户将需要一个类似于他们正在编辑的视觉差异工具。如果他们只是稍微不技术，DocBook或Latex将无法工作（我试过给我的用户，我甚至尝试过Epic Editor作为DocBook编辑器，这个编辑器非常昂贵，但毕竟效果不好。坚持他们所知道的事情（Word）会让你头疼。

我一开始也不愿意走这条路，因为我想要一个更“技术上完美”的解决方案，但随着时间的推移，我意识到拥有快乐和高效的用户更为重要。只是说我知道你来自哪里，但尝试Word路线 - 它在实践中比在那里的所有'纯'基于文本的解决方案更好。普通用户不喜欢基于标记的编辑。

Answer 8

我创建了一个名为Mandown的文档系统（基于Markdown / Html / Javascript /基于文件的相对链接文档以实现可移植性），该系统很容易受版本控制。你必须单独弄清楚的可视化编辑器部分 - 我有时使用HTML-Kit，至少有一个预览功能。

请参阅What is the best way to store software documentation?

---

这是另一个检查工具：Xilize

Answer 9

如果您使用的是Visual Studio，请查看SandCastle - http://www.codeplex.com/Sandcastle。

还有一些工具可以帮助您构建sandcastle文件，尝试在codeplex上搜索“sandcastle”。其中一个是SandCastle帮助文件生成器（http://www.codeplex.com/SHFB），但我从未使用它，所以我不知道非技术用户是否会对此感到满意。

Answer 10

Madcap Flare是最好的商业工具。由Robodoc的前开发人员撰写

Answer 11

我们正在使用APT。它与CI（标准构建工件）很好地集成，并且比例如word文档更活跃。也可以在需要时生成PDF和其他格式。