任何人都可以推荐一个程序来创建用户手册吗？不是一种标记语言（如 LaTeX 或 DocBook），而是更像 Scribus 之类的交互式标记语言。由于我不是唯一会更新手册的软件，因此该软件应该是新手容易上手的软件，但仍具有一些高级功能（例如从外部源/表格链接文本，处理母版页/主题等） .
问候，奥斯卡
finnsson
问问题
7914 次
11 回答
109
技术出版软件——对FrameMaker及其替代品的看法
我已经使用 LaTeX 和 Framemaker 完成了规范文档，并设计了 Framemaker 工作流程来支持由 5 名分析师组成的团队为保险承保系统制作规范文档。该文件预计将达到 2,000 页左右。许多年前（大约 1992 年至 1993 年），我还曾短暂地担任过排字员。
Framemaker 专为技术文档而设计，并且确实做得很好。 它还具有旨在支持具有多个作者的超大型文档的功能——人们使用该系统来处理超过 100,000 页的文档。对于熟悉文字处理软件的用户来说，它也比 LaTeX 更易于访问。
Framemaker的主要特点：
由多个文件组成的文档：您可以将一个“书”与不同文件中的多个小节组合在一起。该文档也可以保存在源代码管理中。
用于导入/导出的文本 MIF 格式：导入器有点挑剔（我发现生成工作 LaTeX 更容易），但您可以生成数据字典等项目并将它们导入文档。该文件具有文本锚（见下文），因此您可以创建跨导入稳定的交叉引用链接。我发现这是规范的一个关键特性，因为它允许交叉引用直接链接到生成的项目。
强大的标签、索引和交叉引用系统：一切都基于 Framemaker 中的标签，易于快速应用标签。这意味着交叉引用、索引、条件文本和整体应用样式很容易而且 很有效。您可以根据标签生成索引和 TOC，因此拥有多个专用索引（例如屏幕或数据字典中的数据字段名称列表）很容易做到。我上面描述的文档有 4 个单独的索引。
稳定： Framemaker 是为专业人士设计的，因此它不会像这个词那样猜测你。它在大型文档上也更加稳定。任何尝试在 Word 上编写超过 50-100 页文档的人都应该非常清楚这意味着什么。
Scriptable： FM 有一个 C API，并且有各种脚本插件（FrameScript和FMPython 可能是使用最广泛的），可用于在 FM 中自动化作业。 Framemaker 10增加了对名为Extendscript的基于 Javascript 的脚本工具的支持，大概是从 InDesign 中的脚本工具移植过来的。
单一来源：从单个 FM 文档，您可以相当轻松地生成 PDF、Windows 帮助 (CHM)、HTML 和打印文档。交叉引用也解析为超链接。
全局样式控件：您可以轻松地为文档设置样式并将其应用于整个文档。它还有助于运行页眉和页脚，并具有很大的灵活性，可以让它们跟踪部分、版本、章节等。
Framemaker的替代品
Ventura Publisher：如果您想要那种用户界面而不为特权支付身体部分，这可能是 Framemaker 的唯一真正替代品。它对结构化文档和基于 XML 的文档交换格式具有强大的支持。它现在归 Corel 所有，Corel 似乎仍在积极推广它。
市场上还有其他几种技术发布工具：Quicksilver （以前称为Interleaf）和ArborText。这两个是强大的工具——Interleaf 曾经一度是该领域的市场领导者——但价格相当昂贵。
Adobe Indesign：尽管 Adobe 声称您可以使用 InDesign 制作大型文档，但 Framemaker 爱好者往往认为交叉引用和其他大型文档功能缺乏。但是，它有一个名为InCopy的文本输入系统，它显然确实具有这种功能和相当多的第三方插件，其中一些确实支持标记和其他此类工具。InDesign 还有一个脚本 API 和一个用于执行脚本的 JavaScript 解释器。
我没有使用过 Indesign，所以我无法评论它在实践中的效果如何。
DocBook： 这实际上只是结构化文档的标准格式，但围绕它有一个庞大的工具生态系统，用于编写和呈现文档。如果您不想使用 LaTeX，您可能出于类似的原因不想使用 DocBook。正如Vinko Vrsalovic 指出的 (+1)，此链接指向StackOverflow 帖子，来自某人描述在实践中使用 DocBook。我从未真正使用过 DocBook，而且我对这篇文章进行了如此多的编辑，以至于它现在处于 Wiki 模式，因此熟悉 DocBook 的人可能想要详细说明这一点。
文字处理软件： Word 作为技术发布工具存在严重缺陷，不推荐使用。 OpenOffice具有比 word 更好的结构化文档功能，如果政治或使用 .doc 作为文档交换格式的要求排除了更好的选择，它可能是更好的选择。 Wordperfect在处理大型文档方面也比 word 好得多，并且仍然存在于多个垂直市场，例如法律办公室。
Madcap Software 的 Blaze和Flare：这些是街区里的新孩子，与 Framemaker 住在大致相同的空间。该公司由前 eHelp（RoboHelp 的创建者）员工创立，并正在积极发展，每年发布多个版本。他们的产品在过去两年中大大扩展，损害了单个产品的质量。似乎重点一直放在生产新产品上，因此每个产品都存在很多“适合和完成”问题。作者选择以多种方式重新发明轮子，从而导致令人困惑且经常被破坏的实现。经常保存，会遇到未处理的异常。源代码控制集成是不稳定的。例如，移动或删除一组文件将导致每次文件删除都提交一个源代码控制提交。当您有源代码控制电子邮件通知时，大 PITA。你好 500 封电子邮件。Flare 可以导入 Word 和 Framemaker 文件，但导入远非无缝。期望保留您的所有内容，但计划从头开始完全重新设计。Flare 与 Word 一样倾向于在幕后做太多事情并假设用户会选择什么。HTML 看起来就像您导出 HTML 时 Word 输出的内容 - 大量自定义标签和属性、深度嵌套的内联样式等。文本编辑器令人抓狂，例如，它的光标模型与您曾经使用过的任何其他软件都不同。
Framemaker 与 LaTeX
这两个是我用来生成大型、美观的系统文档的主要系统，我在这两个方面都取得了很好的效果。
易于学习： TeX 可以为您提供绝对控制，但实际上在不破坏其他项目的情况下在复杂的 LaTeX 文档上实现这一点并非易事，尤其是在涉及大量宏包的情况下。基本的 LaTeX 并不难学，但是如果你不是一个真正深入的 TeX 黑客，那么制作仍然可以工作的 .sty 文件的修改版本需要一些修修补补。这是可以做到的，但要准备好花很多时间摆弄。
Framemaker 可以让您很好地控制文档的外观，而且学习起来并不难。使用 Framemaker 获得房屋风格和调整布局（您可能必须这样做）会更容易。
易于文本输入：您可以使用Lyx等工具为 LaTeX 提供类似文字处理器的前端，如果您想编写大量文本，这些工具可以很好地工作。Framemaker 类似 DTP 的用户界面以习惯文字处理软件的人所熟悉的方式工作。从这个角度看，实际差别不大。
模板化文档结构： Framemaker 允许根据标签或 XML 模式定义文档结构（如果使用结构化 Framemaker）。LaTeX 有一组固定的结构元素，它们足够灵活，非常有用。添加额外的结构元素（例如数据字典项）可以作为宏来完成，但是使它们自动编号更具挑战性，您需要在幕后四处寻找。两者都可以做到，但在 LaTeX 中做这件事的技术性要强得多，而不是微不足道的情况。
此外，LaTeX 没有像 Structured Framemaker 那样对文档结构进行模板化的功能。但是，您可以使用 DocBook 实现这种效果，然后根据需要生成 LaTeX。
易于集成：我发现为非常复杂的 MIF 文件制作一个生成器非常繁琐。MIF 解析器在 FM 中非常棘手，并不能真正提供良好的诊断。LaTeX 会产生更好的错误信息，并且不那么挑剔。
技术出版软件与排版软件
页面布局软件从Pagemaker开始，该领域的其他主要参与者是它的竞争对手Quark Xpess和现在的 InDesign，Adobe 基本上试图用它来弃用和替换它和 Framemaker。 您之前提到的Scribus与这些产品位于同一空间。
如果您制作的手册页数少于（例如）50-100 页，那么其中一个包可能就足够了。它们实际上是为广告和布局繁重的出版任务（如杂志）而设计的，因此它们对 Framemaker 中的大型文档功能的支持相当有限。这些产品的关键问题是可扩展性——它们不适用于大型文档。
仅供参考，我实际上已经使用 Pagemaker 排版了一本 200 页的书（某人的自传）。虽然细粒度的字距调整和前导控制有助于复制拟合，但布置书本大小的文档仍然是一个高度手动的过程。在这种情况下，这本书只是纯文本，除了章节之外没有重要的交叉引用或结构。使用 Pagemaker 编写复杂的技术规范文档或这种大小的手册会非常繁琐，而且可能几乎不可能在没有任何错误的情况下正确完成。
技术出版与文字处理软件
这更多地描述了 MS-Word 对于大型规范文档的主要缺点。但是，它将说明大型文档所需的一些主要功能：
索引和交叉引用：这是 Word 中的一项真正的苦差事，而且非常不稳定。Framemaker 的标记功能和 LaTeX 的标签意味着您可以分配标签或已知标签（必要时以可预测的格式）。标签锚的文本格式在用户界面中公开，并用于链接。在 Word 中，锚点更加不透明，并且不容易以这种方式控制。结合笨拙的用户界面和产品的不稳定性，这使得维护这些繁琐，而且往往不稳定——你经常不得不手动修复它们。
模板化布局： word 中的样式支持非常基本，编号往往有些不稳定。FrameMaker 就是从标签驱动并基于标签应用样式。全局样式更改仅在 Framemaker 中起作用，而在 Word 中则不起作用。
大型多文件文档：我一直无法在 Word 中很好地使用它，但它是 Framemaker 和 LaTeX 中的一个关键特性。同样，Word 的不稳定性意味着您往往会花费大量时间来整理它。随着文档变大，花在这项工作上的时间比例呈二次方增长 - 破损倾向与n（文档大小）成正比 * 修复时间与大小n（修复时间）成正比
为什么 Word 如此不稳定： Word 在幕后做了很多工作来支持新手用户并干预布局。它也不是真正基于框架的（文本流在概念上与文档布局分开），但开发人员尝试在 UI 中实现各种类似框架的行为。当人工智能对复杂文档进行第二次猜测时，它通常会做错事。Framemaker '将用户视为成年人'并且不做任何事情，所以事情会留在你放置它们的地方。
其他文字处理器（例如 Open Office 和 WordPerfect）的行为方式与 Word 并不完全相同，这也是 Word以外的任何文字处理器都能更好地处理技术文档的原因之一。
Pre-Flighting：在文档中，这是在提交打印之前检查文档（图像文件等）的文件组合是否正确的过程。专业系统会抱怨错误的地方，让您有机会纠正它。Word 只会装出一副幸福的表情，并尝试在幕后解决问题。
一个很好的例子是带有链接图形的 word 文件。如果您将文件和图形复制到另一个目录并就地更新其中一个图形，word 很可能仍然从旧路径读取文件（我已经看到它这样做了）而不是您刚刚更新的新路径。然而，这种行为并不一致，并且代表了该产品中对不稳定启发式的猖獗滥用。
印前支持：出版系统延伸到工作流程的印前阶段。这意味着它涵盖了打印准备。文字处理软件往往不具有此功能或具有非常有限的形式。
无需深入探讨，关键区别在于，发布软件倾向于将您视为同意的成年人，而不是在您想要扩展或自动化事物时妨碍您。可以将文字处理软件用于大型文档，但它有许多设计决策适合临时用户编写短文档而很少考虑质量。这些适应是以牺牲大规模文档准备工作的任务适应性为代价的。我发现 Word for spec 文档的主要问题是索引和交叉引用不佳以及一般的不稳定问题，我总是不得不回去修复问题。但是，大多数环境（我是承包商）中的政治考虑意味着人们经常会坚持下去。
关于技术文档软件状态的一些一般性评论
如果 Adobe 没有继续发出他们试图弃用它并将其用户群转移到 InDesign 的信号，那么 Framemaker 将是显而易见的选择。然而，FM 被广泛用于航空航天、软件和工程界，如果 Adobe 的管理层在没有可靠的迁移路径的情况下真的将产品停产，他们将面临一群私刑。从网上了解到的情况来看，Adobe 收购 FM 是由 John Warnock 推动的，但他被赶下台，FM 成为办公室政治的受害者。最终结果是它已被转移到维护模式并且非常停滞不前。
Ventura Publisher 在某种程度上也被归入了一个小众市场，但至少 Corel 没有像 Adobe 那样有两条相互竞争的产品线。它可能是 FM 的一个合格的替代品，并且可能在政治上更容易被 PHB 类型接受，因为它被称为“商业出版”系统。
Quicksilver 和 Arbortext 似乎都是可行的产品，但价格非常昂贵。我也没有使用过，所以我无法对它们的优点做出任何真正的判断。
标记语言系统在许多方面都是免费且非常强大的。Lout 可能更容易使用，因为它没有 LaTeX 那样的遗留包袱。DocBook 也被广泛使用，并且有相当多的工具支持。这些技术极大地挤压了 Framemaker 市场份额的“极客”端，并且这样做是基于它们的优点——它们多年来可能从 Adobe 的利润率中拿走了相当大的一部分。我不会忽视这些技术，但在实践中它们会更难学习。
您可以尝试评估 InDesign 和一组选定的插件（专注于那些用于标记和交叉引用/索引管理的插件）。最后，一些文字处理软件（Wordperfect 和 OpenOffice）为您提供了一个合理的结构化文档工具包，并且在这方面的工作比 MS-Word 好得多。
后记
是的，这是一个双关语。我还没有提到任何这些产品的印前功能。印刷和印前本身就是技术领域，代价高昂的错误范围意味着您可能应该将其留给专家。Framemaker、InDesign、Ventura、QuickSilver、Arbortext 和（大概）MadCap 产品都配备了进行印前准备的设施。总的来说，文字处理软件没有。
使用 LaTeX 进行印前往往涉及使用psutils等软件对 PS 输出进行后处理或渲染为 PDF 并从那里进行印前工作流程。一般来说，大多数印前机构都可以使用 PDF，因此像 Distiller 这样的优秀 PDF 编写工具是使用非印前工作工具准备工作的最佳界面。请注意，Distiller的输出质量往往优于基于Ghostscript的PDFCreator等。
请注意，显示器的 RGB 色彩空间没有直接映射到印刷机使用的 CYMK 色彩空间。如果您没有合适的工具包，实际上要让颜色——尤其是彩色照片——在印刷机上正确打印出来有点令人担忧。对于印刷制作，请咨询专家，除非您有理由相信自己知道自己在做什么。对于一个普通用户，在我涉足这个行业 15 年后，我仍然会推荐这个，因为一旦他们致力于打印错误，修复它们的成本就非常昂贵。
如果您真的想在内部进行彩色打印工作，您可能需要校准您的显示器。为获得最佳效果，您应该从 HP购买一台像这样的高保真显示器。为了校准显示器，如果显示器没有配备传感器，您可能还需要像本评论中描述的传感器之一。Nvidia、AMD或Matrox等大多数专业显卡都具有支持伽马校正的功能；许多消费者也这样做。您还需要获取用于印刷的印刷机的校准数据，尽管印前机构可能能够做到这一点。
如前所述，印刷媒体本身就具有很强的技术性，一旦印刷就容易出错并且修复成本很高。如果您不能 100% 确定您的校准是否正确，请获得像Chromalin这样的颜色证明。这是从实际的胶片分离中完成的（因此非常昂贵），因此它可以准确再现最终印刷品的实际颜色。对几个示例页面执行此操作将为您提供有关校准设置是否正确的准确反馈。
致谢：感谢Aidan Ryan扩展了关于 Madcap 产品的部分。
于 2008-12-16T17:22:38.850 回答
5
我会推荐 EC Software 的“ Help & Manual ”。您可以从单个源文档创建印刷手册、PDF、Windows 帮助文件 (CHM) 和基于 Web 的 HTML 帮助。
于 2008-12-16T17:38:07.413 回答
4
我听说过有关FrameMaker的好消息。我自己没有使用过它，但是为了这样的应用程序向我推荐了它。
于 2008-12-16T15:44:52.947 回答
2
Adobe Framemaker 确实是编写用户手册的经典工具。我已经将它用于各种长文档，并且效果很好。太糟糕了，Adobe 让它腐烂多年，然后才注意到用户不会切换。
MSWord 直到 2003 年才解决项目符号/编号错误，我不知道他们是否最终让主文档工作。
LaTeX 仍然是一个合理的选择。该格式易于处理，您可以从 wiki 生成它。
于 2008-12-16T16:15:29.797 回答
1
如果您想要协作，那么基于语言的方法（LaTeX 将是我的首选，尽管基于 XML 的方法也很好——Docbook 是这里的旗舰）确实有意义，尤其是当您使用版本控制系统跟踪文件时。
任何使事情复杂化的东西，例如任何具有二进制或专有格式的软件，都不会在这里为您提供帮助。
抱歉，如果这不是您想要的答案。
于 2008-12-16T15:40:22.240 回答
1
我同意 Ollivier 的观点，即使用 DocBook（或 LaTEX）是最简单的方法，可以轻松转换、合理的格式、良好的版本控制。
令人高兴的是，您可以尝试使用 DocBook 编辑器制作蛋糕并吃掉它。
试试这个列表中的那些，看看是否有满足你的需求（我没有使用过）。
于 2008-12-16T15:43:58.533 回答
1
我们正在使用EC Software的“帮助和手册” ，它运行良好。我们的作者遍布美国，因此我们通过托管的 SVN 服务器共享我们的内容文件以管理版本控制。在每个工作站上，我们使用 Tortoise SVN 保持同步。该产品非常易于使用和生产。
于 2009-03-09T20:40:29.760 回答
1
A VERY nice explanation on what O'Reilly (actually the ones selling all these books...) uses:
It may seem complicated, but depending on the amount of pages you are going to write you maybe should put some consideration into it.
于 2013-02-24T17:43:27.733 回答
0
Word（或您最喜欢的文字处理器）
我在 Word 中制作所有用户手册（不要与用户帮助文件混淆）。然后我可以确定它们是否需要 PDF、RTF、DOC 甚至转换为 HTML。为了解决多用户更新问题，我将文件存储在源代码管理中，它可以处理所有这些有趣的事情。
于 2008-12-16T15:42:21.063 回答
0
有关使用 DocBook 等权衡的深入讨论，请参阅Fastware Project博客。Scott Meyer 尝试了很多可能性并分享了他的想法。
于 2008-12-16T15:55:57.217 回答
0
Adobe InDesign CS5.5 在交叉引用和长文档方面比早期版本要好得多。它非常强大并且相对容易学习和使用。该功能集非常丰富，您了解的越多，您可以使用它做的事情就越多。它支持非常强大的 XML 功能，可以根据需要导入和导出 XML。它还可以将样式映射到标签，将标签映射到样式，如果您只需使用一整套字符和段落样式，就可以自动创建 XML。我已经使用该程序多年，并制作了从书籍到一次性广告的多个项目。它是一种图形设计工具，但支持书籍和手工制作的许多方面。如果您更关心图形、图像或插图，我推荐它。InDesign 支持多种导入和导出格式。
InDesign CS5.5 添加并改进了对 EPUB（电子书）和 Adobe 的 Digital Publishing Suite (DPS) 电子杂志格式的交互式内容和导出的支持。
Framemaker 是用于书籍、手册和长篇技术文档的绝佳工具。它比 InDesign 更难学习，但如果您有时间和兴趣学习如何使用它们，它有一套更丰富的工具来构建变量和运行页眉和页脚。它还有一个非常健壮的 XML 功能集，但我没有亲自使用过。
Unfortunately, Framemaker suffers from lack of support for graphic design. The color system is based very kludgey and spot (PMS) colors are hard to define. Simple things like adding a stroke color and fill color are rudimentary at best. For example, you still can't select a stroke color that's different from an objects fill color. The program is intended to output to laser and inkjet printers and not really to printing presses.
One feature that is really cool is the ability to apply master pages based on the Paragraph styles appearing on the page. The paragraph/illustration numbering in Framemaker is superior to any other program that I have ever used. But it is also difficult to learn and use.
Both programs support output to PDF and PostScript file formats and can generate hyperlinks and interactive content.
于 2011-11-28T18:53:19.720 回答