什么是编写与版本控制集成的用户手册(帮助文件)的好工具[关闭]

还有其他专业产品允许帮助文件写入,它们支持“上下文ID”,这使得上下文相关的帮助成为可能。 Doc To Help 和 RoboHelp 是这类产品吗?

资料收集库

alt text http://www.docbook.org/graphics/banner.png

Microsoft HTML帮助研讨会可用于创建高质量的专业CHM帮助文件。你只需要一堆HTML文件。该工具将所有这些内容“编译”成一个单独的帮助文件。 HTML文件可以使用Microsoft Word/FrontPage甚至Dreamweaver生成。您可能需要考虑控制这些HTML文件的源代码。

Latex . Lyx 提供用于写入乳胶文件的WYSIWYM。

在我以前的工作中,他们使用了Madcap软件的一个工具,叫做 flare .

看起来效果很好。

要考虑的一个好的组合是颠覆、DocBook和Publican。

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

目前,这是世界上最大的开源解决方案提供商正在使用的工具链之一,也是世界上许多企业市场上使用基于Linux的操作系统背后的名字。Red Hat的大部分(几乎所有)官方文档都是以这种方式创建的。软呢帽也是如此。

这里的主要“pro”是这些工具是免费提供的,在技术作者市场上有很强的重叠。所有这些都可以(但可能不想)用XML编写,而挑选DocBook就像90年代挑选HTML一样。Subversion是一个非常常见的版本控制工具,就像DocBook一样,相对容易实现和使用。Publican是一个很好的发布工具,可以采用DocBook XML,并将其发布为PDF、HTML、HTML Single等。显然,您的作者可以使用像serna这样的Wysiwyg,但我个人使用geany(在fedora上)或textmate(在os x上)中的代码片段。

主要的“骗局”是对技术性的感知。您的作者可能需要所见即所得(并且可以拥有),根据您的文档需求,这可能是您最终使用的。正如你所知道的,有一个市场专门为“技术作家”修理微软的文字样式(和标记),所以把“创作”和“出版”分开的论据是基于那些要求文档符合工程/编程/s相同标准的组织的经验证但不同的用例我们的产品。

您将得到的一些极端建议来自那些已经接触到XML文档价值的人和公司,尤其是那些在DITA领域的人和公司,在那里,某些跨国公司因受产品知识的格式和可用性影响的收购而享有盛誉。还有一些观点认为,将文档锁定为“粘性”或关闭格式对将来的维护需求没有帮助。这就是开源选项在公司级别获得支持的地方。另外,很明显,这是免费的。

您可以使用Subversion和mgtek帮助生成器。帮助生产者从Word文档制作帮助文件。Tortoissesvn自带脚本,用于比较Word文档的不同修订版本(Word有版本比较工具)。

您的用户将需要一个与他们正在编辑的工具类似的视觉差异工具。如果他们只是稍微不专业,DocBook或LaTex就不会工作了(我试过把两者都给我的用户,我甚至试过将Epic编辑器作为DocBook编辑器,这是非常昂贵的,但最终效果不是很好)。坚持他们知道的东西(单词)可以防止你很多头痛。

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

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

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

MapCap Flare是最好的商业工具。由RoboDoc的前开发人员编写

我创建了一个名为 Mandown ( 基于markdown/html/javascript/文件的相对链接文档 对于可移植性)这很容易受到版本控制。视觉编辑器部分,你必须单独考虑-我有时使用 HTML-Kit 它至少有一个预览功能。

见 What is the best way to store software documentation?

下面是另一个要检查的工具: Xilize

我们正在使用 APT . 它与CI(标准构建工件)很好地集成,比Word文档更活跃。还可以在需要时生成PDF和其他格式。