生成用户手册的应用程序（不是标记语言）

Question

生成用户手册的应用程序（不是标记语言）

39

有人可以推荐一个用于创建用户手册的程序吗？不是像LaTeX或DocBook这样的标记语言，而是更像Scribus一样的交互式工具。由于我不是唯一更新手册的人，因此软件应该是一个易于入门的新手可以掌握的东西，同时还具有一些高级功能（例如从外部资源/表格中链接文本，处理主页/主题等）。

问候，奥斯卡

- finnsson

11个回答

5

我建议使用EC Software的“Help & Manual”。您可以从单个源文档创建印刷手册、PDF、Windows帮助文件（CHM）和基于HTML的网络帮助。请看下面的内容：

我建议使用EC Software的“Help & Manual”。您可以从单个源文档创建印刷手册、PDF、Windows帮助文件（CHM）和基于HTML的网络帮助。

- Craig Lebakken

我已经使用过它，可以将手动源代码存储为XML格式，因此可以轻松地将其添加到源代码控制中。 - Marc Climent

4

我听说过关于FrameMaker的好评。虽然我自己没有用过，但是别人曾经向我推荐过它来完成这样的应用。

- Peter K.

2

我使用过FrameMaker。它是创建软件手册的最佳产品，但不适合新手。 - Bill Karwin

2

同意。自1990年以来使用FM，没有替代品（“经常被模仿，从未被复制”）。 - Dan

2

Adobe Framemaker是编写用户手册的经典工具。我用它来处理各种长篇文档，效果很好。可惜Adobe在多年后才注意到用户不会转换，让这个工具被搁置了很久。

MSWord直到2003年才解决了项目符号/编号问题，我不知道他们是否最终让主控文件正常工作。

LaTeX仍然是一个合理的替代方案。该格式易于处理，您可以从wiki生成它。

- Stephan Eggermont

1

以下是关于 O'Reilly（实际上是出售这些书籍的人……）所使用的工具链的非常好的解释:

O'Reilly 工具链

这可能看起来很复杂，但根据您要编写的页面数量，您可能应该仔细考虑一下。

- sjas

1

如果您想要协作，那么基于语言的方法（我会首选LaTeX，尽管基于XML的也不错，其中 Docbook 是旗舰产品）确实是有意义的，特别是如果您正在使用版本控制系统跟踪文件。

任何使事情变得复杂的东西，比如任何具有二进制或专有格式的软件，在这里都没有帮助。

很抱歉如果答案不是您想要的。

- Ollivier Robert

1

我同意Ollivier的观点，使用DocBook（或LaTEX）是最明智的方法，可以轻松转换，格式合理，版本控制良好。

令人高兴的是，您可以尝试使用DocBook编辑器来实现双赢。

请尝试此列表中的编辑器，看看是否有满足您需求的（我没有使用过任何一个）。

- Vinko Vrsalovic

1

我们正在使用EC Software的“Help & Manual”，它运行良好。我们的作者分布在美国各地，因此我们通过托管的SVN服务器共享内容文件以管理版本控制。在每个工作站上，我们使用Tortoise SVN保持同步。该产品非常易于使用和高效。

- user61079

0

Word（或您喜欢的文字处理软件）

我所有的用户手册（不要与用户帮助文件混淆）都是用Word制作的。然后，我可以确定它们需要以PDF、RTF、DOC甚至转换为HTML的形式呈现。为了解决多用户更新问题，我将文件存储在源代码控制中，这可以处理所有有趣的事情。

- Stephen Wrighton

我们在我上一个项目中使用了Word和SourceSafe来进行文档编写。由于手册非常长，我们不得不将每个部分保存在单独的文件中。我们使用Adobe Acrobat将所有的Word文档转换为PDF格式，然后将PDF文件合并成每个手册一个PDF文件。 - Scottie T

0

请查看Fastware项目博客，深入讨论使用DocBook等的权衡。Scott Meyer尝试了很多可能性，并分享了他的想法。

- John D. Cook

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- NXC · Accepted Answer

技术出版软件 - FrameMaker及其替代方案的看法

我使用过LaTeX和Framemaker制作规格说明文件，并设计了一个Framemaker工作流程，以支持一个由5名分析师组成的团队为保险核保系统制作规格说明文档。该文档预计需要达到2,000页左右。很多年前（约1992-1993年），我还曾短暂地担任过排版员。

Framemaker是专为技术文档而设计的，确实做得非常好。它还具有设计用于支持具有多个作者的大型文档的功能 - 人们使用此系统制作了超过100,000页的文档。与LaTeX相比，对于熟悉文字处理软件的用户来说，它也更易于使用。

Framemaker的主要特点:

由多个文件组成的文档：您可以将多个子部分位于不同文件中的“书”汇集在一起。该文档也可以保存在源代码控制中。
用于导入/导出的文本MIF格式：导入程序有点挑剔（我发现生成可工作的LaTeX更容易），但您可以生成诸如数据字典之类的项目并将其导入文档。该文件具有文本锚点（见下文），因此您可以创建跨引用链接，这些链接将在导入时保持稳定。我认为这是规格说明的关键功能，因为它允许交叉引用直接链接到生成的项目。
强大的标记、索引和交叉引用系统：一切都基于Framemaker中的标记，而且很容易快速应用标记。这意味着交叉引用、索引、条件文本和批量应用样式非常容易，并且可以根据标记生成索引和目录，因此很容易制作多个专业化索引（例如来自屏幕或数据字典的数据字段名称列表）。上述描述的文档有4个单独的索引。
稳定性：Framemaker是专为专业人士设计的，因此它不像Word那样对您进行二次猜测。在处理大型文档时，它也更加稳定。任何曾经尝试在Word上编写超过50-100页文档的人都应该很清楚这意味着什么。
可脚本化：FM具有C API，并且有各种脚本插件（FrameScript和FMPython可能是最广泛使用的），可以用于自动化FM中的作业。Framemaker 10增加了对基于Javascript的脚本工具Extendscript的支持，这很可能是从InDesign的脚本功能移植过来的。
单一来源：从单个FM文档中，您可以相当容易地生成PDF、Windows帮助（CHM）、HTML和打印文档。交叉引用还会解析为超链接。
全局样式控制：您可以轻松设置文档样式并将其应用于整个文档。它还促进了具有很大灵活性的页眉和页脚，使它们跟踪节、版本、章节等。

替代Framemaker的选择

LaTeX/Lout: 您已经表明您不想使用标记语言，但是TeX和Lout系统用于大型结构化文档，并且执行得很好。
Ventura Publisher: 如果您想要这种用户界面而又不想付出身体部位的代价，那么这可能是Framemaker唯一真正的替代品。它对结构化文档有很强的支持，并具有基于XML的文档交换格式。现在它由Corel拥有，他们似乎仍然在积极推广它。

市场上还有其他几款技术出版工具：Quicksilver（曾被称为Interleaf）和ArborText。这两款工具功能强大- Interleaf曾经是该领域的市场领导者- 但价格相当昂贵。
Adobe Indesign: 尽管Adobe声称您可以使用InDesign处理大型文档，但交叉引用和其他大型文档功能通常被认为是Framemaker专家所缺乏的。然而，它有一个名为InCopy的文本输入系统，据说具有此类功能和相当大量的第三方插件，其中一些支持标记和其他类似的功能。InDesign还具有脚本API和JavaScript解释器以执行脚本。

我没有使用过Indesign，所以我无法真正评论它在实践中的表现。
DocBook: 这实际上只是结构化文档的标准格式，但围绕它有大量的工具生态系统用于编写和呈现文档。如果您不想使用LaTeX，您可能不会选择使用DocBook出于类似的原因。正如Vinko Vrsalovic（+1）指出的那样，This link链接到一个StackOverflow帖子，其中有人描述了在实践中使用DocBook的情况。我从未真正使用过DocBook，并且对这篇文章进行了很多编辑，现在它已经进入了Wiki模式，因此熟悉DocBook的人可能需要详细说明一下。
文字处理软件：Word作为技术出版工具存在严重缺陷，不建议使用。OpenOffice比Word具有更好的结构化文档功能，如果政治或要求使用.doc作为文档交换格式，则可能是更好的选择。Wordperfect在大型文档的文档编写方面也比Word好得多，并且在法律办公室等几个垂直市场中仍然存在。
Madcap Software's Blaze和Flare：这些是新生代的产品，与Framemaker大致处于同一领域。该公司由前eHelp（RoboHelp的创建者）员工创立，正在积极开发，每年发布多个版本。他们的产品在过去两年中大大扩展了，但个别产品的质量受到了影响。他们似乎专注于推出新产品，因此每个产品都有许多“适合和完成”问题。作者在许多方面选择重新发明轮子，导致实现混乱且经常出现故障。经常保存，您将
Framemaker与LaTeX

这两个系统是我用来制作大型、可呈现的系统文档的主要工具，我使用它们都获得了不错的效果。
- 学习难度：TeX可以给你绝对的控制力，但在不破坏其他项目的情况下实现复杂LaTeX文档的控制并不容易，特别是涉及大量宏包的情况下。基本的LaTeX并不难学，但如果你不是TeX专家，要制作仍然可用的.sty文件的修改版本需要花费一些时间来调试。虽然这是可以做到的，但是要准备花费很多时间。
  
  Framemaker可以让您对文档外观有很好的控制，并且也不难学。使用Framemaker更容易获得一个统一的样式和微调布局。
- 输入文本的便捷性：您可以使用Lyx等工具为LaTeX提供类似于文字处理软件的前端，如果您想编写大量的文本，则这些工具效果很好。Framemaker的DTP式用户界面以熟悉文字处理软件的方式工作。从这个角度来看，两者之间没有太大的实际差异。
- 模板化文档结构：Framemaker允许通过标签或XML模式（如果使用Structured Framemaker）来定义文档结构。LaTeX有一组灵活的预定义结构元素。添加其他结构元素（例如数据字典项）可以作为宏完成，但是使它们自动编号要更具挑战性，您需要深入了解LaTeX内部。两者都能做到这一点，但在除了简单情况之外的LaTeX中，技术要求相对较高。
  
  此外，LaTeX没有像Structured Framemaker那样模板化文档结构的功能。但是，您可以使用DocBook实现这种类型的效果，然后如果需要生成LaTeX。
- 集成便捷性：我发现制作复杂MIF文件的生成器相当繁琐。FM中的MIF解析器非常挑剔，而且没有提供良好的诊断信息。LaTeX产生更好的错误消息，并且不那么麻烦。
技术出版软件与排版软件

页面排版软件始于Pagemaker，该领域的其他主要竞争者是Quark Xpress和现在的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中实现各种类似框架的行为。当AI在复杂文档上猜错时，它经常会做错事情。Framemaker“将用户视为成年人”，并且不会做任何这样的事情，因此内容会停留在您放置它们的位置。
  
  其他文字处理软件（如Open Office和WordPerfect）不会像Word一样表现不良，这是技术文件几乎使用任何文字处理软件而不是Word的原因之一。
- 预检: 在文档术语中，这是在提交打印之前检查文档的文件组装（图像文件等）是否正确的过程。专业系统将抱怨有错误的事物，并给您纠正的机会。Word将只会摆出愉快的面孔，并尝试在幕后修复问题。
  
  这个问题的一个很好的例子是具有链接图形的单词文件。如果您将文件和图形复制到另一个目录并在原地更新其中一个图形，则Word可能仍然从旧路径（我见过它这样做）读取文件，而不是您刚刚更新的新路径。但是，这种行为并不一致，代表了该产品中不稳定启发式算法的猖獗滥用。
- 印前支持: 发布系统扩展到工作流程的印前阶段。这意味着它涵盖了准备打印的内容。文字处理软件往往没有此功能或以非常有限的形
  不要深入讨论，一个关键差异是出版软件倾向于将您视为成年人并在您想要扩展或自动化事物时不会妨碍您。可以使用文字处理软件进行大规模文档编写，但它具有许多适应于短文档的休闲用户的设计决策，对于大规模文档准备工作来说这些适应性是以适合任务的代价而来的。我在Word中发现的主要问题是索引和交叉引用的质量较差以及一般的不稳定性问题，我总是不得不回去修复问题。然而，在大多数环境（我是承包商）中的政治考虑意味着人们经常被困在其中。
  
  关于技术文档软件状态的一些普遍评论
  如果Adobe没有一直试图废弃并将其用户群转移到InDesign，那么Framemaker将是显而易见的选择。然而，FM在航空航天、软件和工程领域广泛使用，如果Adobe在没有可信的迁移路径的情况下真正终止该产品，那么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）都具有支持伽马校正的功能；许多消费级产品也有此功能。您还需要获取要使用的印刷机的校准数据，尽管印前制作公司可能能够提供此服务。
  作为先前所述，印刷媒体在技术方面相当复杂，容易出错，并且一旦印刷完成，修复成本很高。如果您不确定已经正确校准，请获取像Chromalin这样的颜色校准样张。这是从实际的胶片分离图做出的（因此非常昂贵），因此它可以精确地呈现最终印刷文章的实际颜色。对于一些样张页执行此操作将为您提供有关您的校准是否设置正确的准确反馈。
  致谢：感谢Aidan Ryan扩展有关Madcap产品的部分。