应用程序(不是标记语言)用于制作用户手册

任何人都可以推荐一个程序来创build用户手册? 不是一种标记语言(如LaTeX或DocBook),但更像Scribus的互动。 由于我并不是唯一一个能够更新手册的软件,所以对于初学者来说,这个软件应该是很容易的,但是仍然有一些先进的function(比如从外部来源/表格链接文本,处理主页/主题等) 。

问候,奥斯卡

技术出版软件 – 关于FrameMaker及其替代scheme的看法

我使用LaTeX和Framemaker完成了规范文档,并devise了一个Framemaker工作stream程来支持由5位分析师组成的团队,为保险承保系统生成规格文档。 该文件预计将达到2000页左右。 很多年前(大约在1992 – 1993年),我也曾经作为一名排版工作者做过简单的工作。

Framemaker专为技术文档而devise, 确实做得非常好。 它还具有devise用于支持具有多个作者的大文档的function – 人们使用该系统来处理超过100,000页的文档。 熟悉文字处理软件的用户比LaTeX更容易获得。

Framemaker的主要特点:

  • 由多个文件组成的文档:您可以将不同文件中的多个小节放在一起。 该文件也可以保存在源代码pipe理中。

  • 用于导入/导出的文本MIF格式:导入程序有点挑剔(我发现生成工作LaTeX更容易),但是您可以生成数据字典等项目并将其导入到文档中。 该文件具有文本锚定(见下文),因此您可以创build交叉引用链接,这些链接在导入时将保持稳定。 我觉得这是规范的一个关键特性,因为它允许交叉引用直接链接到生成的项目。

  • 强大的标记,索引和交叉引用系统:一切都基于Framemaker中的标签,并且很容易快速应用标签。 这意味着交叉引用,索引,条件文本和应用样式en-masse很容易, 只是工作 。 您可以基于标签生成索引和TOC,因此可以很容易地实现多个专用索引(例如来自屏幕或数据字典的数据字段名称列表)。 我上面描述的文件有4个单独的索引。

  • 稳定: Framemaker是为专业人士devise的,所以它不会以这种方式猜测你。 在大文件上它也更稳定。 任何试图在Word上编写超过50-100页文档的人都应该对这意味着什么有一个相当公正的想法。

  • 脚本化: FM有一个C API,并且有各种脚本插件( FrameScript和FMPython可能是使用最广泛的),可以用来在FM中自动执行作业。 Framemaker 10添加了对基于Javascript的脚本工具(称为Extendscript)的支持 ,大概是从InDesign的脚本工具中移植过来的 。

  • 单一来源:从一个单一的FM文件,您可以很容易地生成PDF,Windows帮助(CHM),HTML和打印文档。 交叉引用也parsing为超链接。

  • 全局样式控件:您可以轻松地为文档设置样式并将其应用于整个文档。 它还有助于页眉和页脚的运行,使其能够跟踪段落,版本,章节等。

Framemaker的替代品

  • LaTeX / Lout:您已经表示不需要标记语言,但是TeX和Lout系统用于大型结构化文档,并且做得很好。

  • 文图拉出版商:如果你想要这样的用户界面,而不支付身体部分的特权可能是唯一真正的替代框架。 它对结构化文档和基于XML的文档交换格式有强大的支持。 它现在由Corel拥有,似乎仍在积极地推广它。

    市场上还有一些其他的技术发布工具: Quicksilver (以前称为Interleaf )和ArborText 。 这两个是强大的工具 – Interleaf一度曾经是这个领域的市场领导者 – 但相当昂贵。

  • Adobe Indesign:尽pipeAdobe宣称您可以使用InDesign制作大型文档,但交叉参考和其他大型文档function往往被Framemaker的效率视为不足。 然而,它有一个名为InCopy的文本input系统,显然确实有这种function和相当大量的第三方插件 ,其中一些插件支持标签和其他设施。 InDesign还具有用于执行脚本的脚本API和JavaScript解释器。

    我还没有使用Indesign,所以我不能真正评论它在实践中的效果。

  • DocBook:这实际上只是一个结构化文档的标准格式,但是在编写和呈现文档方面有很大的工具生态系统。 如果你不想使用LaTeX,你可能不想使用DocBook出于类似的原因。 正如Vinko Vrsalovic指出的那样(+1), 这个链接从实践中描述使用DocBook的人转到了StackOverflow。 我从来没有真正使用过DocBook,而且我对这篇文章做了很多修改,现在处于Wiki模式,所以熟悉DocBook的人可能想详细说明一下。

  • 文字处理软件: Word作为技术性的出版工具存在严重的缺陷,不build议使用。 OpenOffice比Word有更好的结构化文档function,如果政治或要求使用.doc作为文档交换格式排除更好的select,则可能是更好的select。 Wordperfect在文档方面也比文档大得多,在法律事务所等几个垂直市场仍然占有一席之地。

  • Madcap Software的 Blaze和Flare :这些都是新手,和Framemaker大致相同。 该公司由前eHelp(RoboHelp的创始人)员工创立,并正在积极开发,每年发布多个版本。 在过去的两年里,他们的供应量大大增加,损害了个别产品的质量。 似乎重点放在推出新产品上,结果是每个产品都有很多“合适和完成”的问题。 作者select以多种方式重新发明轮子,导致混淆和经常破坏的实现。 经常保存,您将遇到未处理的exception。 源控制整合是片状的。 例如,移动或删除一组文件将导致每个文件删除提交一个源代码控制。 大PITA,当你有源代码pipe理电子邮件通知。 你好,500封电子邮件。 Flare可以导入W​​ord和Framemaker文件,但导入远不是无缝的。 期望保留所有的内容,但从头开始完全重新devise样式。 Flare分享了许多Word的诀窍,在幕后做了太多的事情,并假设用户会select什么。 HTML看起来像是当你输出HTML时Word输出的内容 – 大量的自定义标签和属性,深度嵌套的内联样式等等。文本编辑器令人生气,例如,它的光标模型与以前使用过的任何其他软件都不一样。

Framemaker与LaTeX

这两个是我用来生成大型的,可展示的系统文档的主要系统,而且我已经有了两个好的结果。

  • 学习的容易性: TeX可以给你绝对的控制权,但是实际上在复杂的LaTeX文档上实现这个function而不会破坏其他项目并不是微不足道的,尤其是在涉及大量macros包的情况下。 基本的LaTeX并不难学,但是如果你不是一个非常深的TeX黑客,那么修改后的.sty文件的修改版本仍然有效。 这可以做,但准备花费相当多的时间摆弄。

    Framemaker可以给你一个很好的程度控制文件的外观,并不难学。 使用Framemaker,获得房屋风格和调整布局(您可能必须做的)将会更容易。

  • 文本input简单:您可以使用像Lyx这样的工具为LaTeX提供类似字处理器的前端,如果您想要编写大量文本,这些工作将会很顺利。 Framemaker的类似于DTP的用户界面的工作方式对那些习惯于使用软件的人来说是很熟悉的。 从这个angular度来看,几乎没有实际的区别。

  • 模板化文档结构: Framemaker允许根据标签或XML模式(如果使用Structured Framemaker)来定义文档结构。 乳胶有一套jar头结构元素,足够灵活,有用。 添加额外的结构元素(例如数据字典项目)可以作为一个macros来完成,但是使它们自动编号更具挑战性,您将需要在幕后进行探究。 两者都可以做到这一点,但是在LaTeX中,除了微不足道的事情外,更重要的是技术。

    另外,LaTeX没有像Structuremaker框架那样对文档结构进行模板化。 但是,您可以使用DocBook实现这种效果,然后在需要时生成LaTeX。

  • 易于集成:我发现为非复杂的MIF文件制作一个生成器非常麻烦。 MIF语法分析器在FM中是非常不合适的,并不能真正提供良好的诊断。 LaTeX产生更好的错误信息,而且不那么挑剔。

技术出版软件与布局软件

页面布局软件以Pagemaker开始,其他主要参与者是其竞争对手Quark Xpess和现在的InDesign,而Adobe本质上正试图反对并取代Framemaker。 你之前提到的Scribus和这些产品在同一个空间里。

如果你制作的手册less于(比如说)50-100页,其中一个软件包可能会做足够的工作。 它们是专门为广告和布局繁重的刊物(如杂志)devise的,所以它们对Framemaker中的大型文档function的支持是相当有限的。 这些产品的关键问题是可扩展性 – 在大型文档上效果不佳。

仅供参考,我实际上使用Pagemaker排版了一本200页的书(某人的自传)。 虽然精细的字距和领先控制有助于装修,但它仍然是一个高度手动的过程,以布局一本书大小的文件。 在这种情况下,这本书只是直接的文本,没有明显的交叉引用或除章节之外的结构。 用Pagemaker制作一个复杂的技术规格文档或手册这种大小将非常复杂,可能几乎不可能没有任何错误地得到正确的。

技术出版与文字处理软件

这更多的是描述大规格文档的MS-Word的主要缺点。 但是,它将说明一些大型文档所需的主要function:

  • 索引和交叉引用:在Word中这是一件很麻烦的事,而且很不稳定。 Framemaker的标签function和LaTeX的标签意味着您可以分配一个标签或已知的标签(如果需要,可预测的格式)。 标签锚的文本格式暴露在用户界面中,用于链接。 在Word中,锚点更不透明,不容易以这种方式控制。 结合笨拙的用户界面和产品的不稳定性,这使得维护这些繁琐,而且往往不稳定 – 你经常不得不手动修复它们。

  • 模板化布局:单词中的样式支持是非常基本的,编号往往有些不稳定。 FrameMaker全部是从标签驱动,并基于标签应用样式。 全球风格的变化在Framemaker中的工作方式,他们不在Word中。

  • 大型多文档文档:我从来没有能够在Word中很好地工作,但它是Framemaker和LaTeX的一个关键特性。 同样,Word的不稳定性意味着你往往花费大量的时间来整理它。 随着文件越来越大,这项工作花费的时间比例呈现二次增长 – 破损倾向与n (文件大小)成正比*固定时间与n的大小成比例(固定时间)

  • 为什么Word如此不稳定: Word在幕后做了很多工作,以支持新手用户并介入布局。 它也不是真的基于框架(文本stream从概念上与文档布局分开),但开发人员尝试在UI中实现各种框架式的行为。 当人工智能第二次猜测你是一个复杂的文件时,往往会做错误的事情。 Framemaker'将用户视为成年人',而不会做任何事情,所以事情留在你把它们放在哪里。

    其他的文字处理软件,如Open Office和WordPerfect,其运行方式与Word完全一样,这也是除了Word以外的其他文字处理软件都能更好地处理技术文档的原因之一。

  • Pre-Flighting:在文档说话中,这是在提交打印之前检查文档(图像文件等)文件的组合是否正确的过程。 专业系统会抱怨错误的事情,给你一个改正的机会。 Word只会expression一个快乐的脸,并试图在幕后解决问题。

    一个很好的例子就是带有链接graphics的文件。 如果您将文件和graphics复制到另一个目录并在原地更新其中一个graphics,则单词可能仍会从旧path中读取文件(我已经看到了这一点),而不是刚刚更新的新文件。 然而,这种行为并不一致,并且代表了该产品中不稳定启发式的猖獗滥用。

  • 印前支持:发布系统延伸到工作stream程的印前阶段。 这意味着它包括准备打印。 文字处理软件往往不具备这种function或以非常有限的forms。

没有太深入的分析,一个关键的区别是发布软件倾向于把你当成一个自愿的成年人,而不是想要扩展或自动化的事情。 人们可以使用文字处理软件进行大规模的文档编辑,但是它有很多devise决策,适合临时用户在写短文档时不注重质量。 这些适应是以大规模的文件准备工作的适应性为代价的。 我在Word中find的关于spec文档的主要问题是糟糕的索引和交叉引用以及一般的不稳定性问题,我总是不得不回头修复这些问题。 然而,在大多数环境(我是承包商)的政治考虑意味着经常卡住它。

关于技术文档软件状态的一些一般评论

如果Adobe没有不断发出信号,表示他们正试图贬低它,并将其用户基础转移到InDesign,那么Framemaker将是明智的select。 然而,FM广泛应用于航空航天,软件和工程领域,如果Adobe没有可靠的迁移path,他们实际上使用该产品,那么Adobe的pipe理层将面临一场暴徒 。 从网上的文章中可以看出,Adobe对FM的收购是由John Warnock所推动的,但他被赶下台了,FM成了办公室政治的受害者。 最终的结果是它已经转移到维护模式,并且停滞不前。

文图拉出版商在某种程度上也被放到了一个小众市场,但至lessCorel没有像Adobe那样有两个竞争的产品线。 这可能是FM的可靠替代品,PHBtypes在政治上可以接受,因为它被作为“商业出版”系统销售。

Quicksilver和Arbortext似乎都是可行的产品,但是非常昂贵。 我也没有用过,所以我真的不能真正的判断他们的优点。

标记语言系统在许多方面都是免费且非常强大的。 Lout可能更容易处理,因为它没有LaTeX那样的传统包袱。 DocBook也相当广泛的使用,并有相当多的工具支持。 这些技术严重挤压了Framemaker市场份额的“极客”端, 并且这样做的优点 – 他们可能已经占用了Adobe多年来的利润空间。 我不会忽略这些技术,但在实践中学习会更困难。

您可以尝试评估InDesign和一组选定的插件(专注于标记和交叉引用/索引pipe理)。 最后,一些文字处理软件(Wordperfect和OpenOffice)为您提供了一个合理的结构化文档工具包,比MS-Word更好地工作。

后记

是的,这是一个双关语。 我没有触及任何这些产品的印前function。 印刷和印前是技术领域本身的权利和昂贵的错误的范围意味着你可能应该留给专家。 Framemaker,InDesign,Ventura,QuickSilver,Arbortext和(据推测)MadCap产品都配备了印前准备工具。 总的来说,文字处理软件没有。

使用LaTeX进行印前处理往往涉及使用诸如psutils之类的软件对PDF输出进行后期处理,或者将其转换为PDF格式,并从那里采用印前工作stream程。 一般来说,大多数印前印刷厂可以使用PDF格式,所以像Distiller这样的PDF书写工具是使用不是为印前工作devise的工具准备的最佳工作界面。 请注意, Distiller的输出质量往往比基于Ghostscript的PDFCreator更好。

请注意,显示器的RGB色彩空间没有直接映射到印刷机使用的CYMK色彩空间。 实际上,如果您没有合适的工具包,那么在印刷机上正确地将颜色(尤其是彩色照片)正确地印出来会有些困难。 对于印刷生产,除非你有理由相信你知道你在做什么,否则去看专家。 对于一个偶然的用户,我仍然会在我介入这个行业15年后推荐它,因为一旦他们承诺打印,错误的修复费用非常高。

如果您真的想在内部进行彩色打印工作,您可能需要校准显示器。 为了获得最佳效果,您应该获得HP这样的高保真显示器。 为了校准显示器,如果显示器没有附带的显示器,您可能还需要像本次审查中描述的传感器之一的传感器。 大多数来自Nvidia , AMD或Matrox的专业显卡都有设备来支持伽马校正; 许多消费者也是如此。 您还需要获得将要用于印刷的印刷机的校准数据,尽pipe印前印刷厂可能会这样做。

如前所述,印刷媒体本身是非常技术性的,一旦印刷出来就容易出错,而且价格昂贵。 如果你不能100%确定你的校准是正确的,可以拿一个Chromalin的颜色certificate。 这是从实际的胶片分离(因此非常昂贵)完成的,所以它给出了最终印刷品的实际颜色的准确再现。 这样做几个样本页面会给你准确的反馈,你的校准是否设置正确。

致谢:感谢Aidan Ryan扩展Madcap产品部分。

我会推荐EC软件的“ 帮助和手动 ”。 您可以从单个源文档创build打印手册,PDF,Windows帮助文件(CHM)和HTML基于Web的帮助。

我听说过有关FrameMaker的好消息。 我自己并没有使用过它,但是有推荐给我的只是这样一个应用程序。

Adobe Framemaker确实是编写用户手册的经典工具。 我用它来处理各种长文档,效果很好。 太糟糕了,Adobe让它腐烂多年,才注意到用户不会切换。

直到2003年MSWord得到子弹/编号错误,我不知道他们是否最终得到主文档工作。

乳胶仍然是一个合理的select。 这个格式很容易处理,你可以从wiki中生成。

如果你需要协作,那么基于语言的方法(LaTeX将是我的偏好,虽然基于XML的方法也是好的 – Docbook是旗舰),这是合理的,特别是如果你使用版本控制系统跟踪文件。

任何使二进制或专有格式的软件复杂化的东西都不会帮助你。

对不起,如果这不是你想要的答案。

我同意Ollivier使用DocBook(或LaTEX)是最简单的转换方式,理智的格式,漂亮的版本控制。

令人高兴的是,您可以尝试使用DocBook编辑器来制作您的蛋糕。

试试这个名单上的人 ,看看是否有任何满足您的需求(我没有使用任何)。

我们正在使用EC软件的 “帮助和手动”,它工作得很好。 我们的作者遍布美国,所以我们通过托pipe的SVN服务器共享我们的内容文件来pipe理版本控制。 在每个工作站上,我们都使用Tortoise SVN来保持同步。 该产品非常易于使用和生产。

关于O'Reilly(实际上销售所有这些书的人)使用的一个非常好的解释:

O'Reilly工具链

这可能看起来很复杂,但根据你要写的页面数量,你应该考虑一下。

字(或你最喜欢的文字处理器)

我在Word中制作所有用户手册(不要与用户帮助文件混淆)。 然后,我可以确定他们是否需要在PDF,RTF,DOC甚至转换为HTML。 为了解决多用户更新问题,我将这个文件存储在源代码pipe理中,它处理所有这些有趣的事情。

请参阅Fastware Project博客,以深入讨论使用DocBook等的权衡。Scott Meyer已经尝试了很多可能性,并分享了他的想法。

Adobe InDesign CS5.5在交叉引用和长文档上比早期版本更好。 这是非常强大的,相对容易学习和使用。 function集非常丰富,您学习的越多,就越可以使用它。 它支持非常强大的XMLfunction,并可以根据需要导入和导出XML。 它还可以将样式映射到标签和标签,使样式可以让您以自动方式创buildXML,只需使用一整套字符和段落样式即可。 我已经使用了这个程序多年,并从书籍到一次性广告制作了多个项目。 这是一个平面devise工具,但支持书籍和手工生产的许多方面。 我推荐它,如果你更关心的graphics,图像或插图。 InDesign支持大量的导入和导出格式。

InDesign CS5.5增加并改进了对EPUB(电子书)和Adobe的数字出版套件(DPS)电子杂志格式的互动内容和导出的支持。

Framemaker是书籍,手册和长期技术文档的绝佳工具。 如果您有足够的时间和倾向来学习如何使用它们,那么学习比InDesign要难一些,但是有更丰富的工具来构buildvariables和运行页眉和页脚。 它也有一个非常强大的XMLfunction集,但我没有亲自使用它。

不幸的是,Framemaker缺乏对graphicsdevise的支持。 颜色系统是基于非常kludgey和现货(PMS)的颜色很难界定。 简单的事情,如添加一个笔触颜色和填充颜色是最好的。 例如,您仍然无法select与对象填充颜色不同的笔触颜色。 该计划旨在输出到激光和喷墨打印机,而不是印刷机。

一个非常酷的function是能够应用基于页面上出现的段落样式的母版页。 Framemaker中的段落/插图编号优于我曾经使用过的任何其他程序。 但是学习和使用也很困难。

这两个程序都支持输出为PDF和PostScript文件格式,并可以生成超链接和交互式内容。