标签：
原文：How to Publish a Great User Manual
地址：http://www.asktog.com/columns/017ManualWriting.html
When was the last time you curled up in bed with a really good user-manual just for the sheer joy of reading it? Never? Think that is some immutable law of nature, like the one that dictates all textbooks must be dull as dirt? ‘Tain‘t so, McGee.
你上一次基于兴趣而躺在床上看用户手册是什么时候呢？从不？就像所有教科书都是枯燥无味的一样，认为那是不可改变的自然法则？
Conflict Catcher is a must-have utility for anyone doing serious work on the Macintosh. It makes visible and helps troubleshoot the myriad mysterious add-ons that clutter the Mac OS. It has the perfect profile for being shipped with a manual that is both dull and unintelligible, but, apparently, someone screwed up, because it is shipping with one of the most witty, delightful, and lucid manuals I‘ve ever come across. Good enough to read just for the sheer pleasure. Why? Because its author, David Pogue, is a gifted writer—always an advantage—and because he has followed the principles of manual design that ensure success.
Conflict Catcher是所有使用Macintosh（一款苹果电脑）进行严肃工作的人所必须的工具。它使堆满Mac操作系统的各种难以理解的插件可见，并帮助排错。它本应附带一份迟钝且莫名其妙的手册，但是，显然，有人搞砸了，因为它的手册是我读过最诙谐、有趣、清晰的手册。好的只是为了完全的享受而阅读它。为什么呢？因为它的作者 David Pogue ，是一个很有才华的作家—这永远是一个优势—而且他遵循了确保手册设计成功的准则。
Steps to overcoming RTFM
克服RTFM（Read The Freaking Manual 读这该死的手册）的步骤
Software manuals tend to come in two flavors—dull and unintelligible. This has led directly and inexorably to RTFM!, the rallying cry of technical support people everywhere. Yet twenty years of yelling at callers to Read The Freaking Manual (or words to that effect) hasn‘t helped. Fixing the manual does. Follow these five easy steps, and your company will start saving big-time on the cost of customer support.
软件手册有两个特色—迟钝和令人费解。这直接导致所有的技术支持人员喊出了RTFM的口号。然而长达二十年的呼喊“读这该死的手册”或其他同样效果的语句，是没有任何帮助的。只是更加坚定了手册的表现。按照下面五个简单的步骤，你的公司将可以在客户支持上节省大量的时间。
1) Supply a (real) manual.
1）提供一份（真正的）手册
An amazing number of companies rationalize their way out of supplying a manual at all, then complain as loudly as anyone else about the stupid users calling customer support.
大量的公司对于他们提供的手册进行据理解释，大声的抱怨用户的愚蠢。
A manual, since many people apparently don‘t know, is made of ground-up dead tree. Those delightful little PDF files that people insist on including on their CD ROM don‘t make it. First, my experience has been that Acrobat only opens around 40% of the time. (The rest of the time either it is distressed because it can‘t find some infinitely important font it wants or I‘ve already got as many windows open as the OS can handle.) Second, even when it does open, these electronic manuals are not only difficult to read, they are anything but portable. (My 20" monitor is way to heavy to crawl into bed with, and I hate trying to read 400 page print-outs.) Besides, I just spent $395 for this software, and all you gave me was an 89-cent piece of plastic? Get real!
显然许多人都不知道，一份手册是由地面上的死树构成（？不太明白）。那些人们坚持放在光盘中的小的令人高兴的PDF文件不能称之为手册。首先，我的经验是Acrobat只有40%的时间被打开。（其余的时间既不能用它找到一些极其重要的信息，而且我已经打开了太多的窗口以至于操作系统无法负荷）。第二，即时是打开的时候，这些电子手册不只是难以阅读，而且很不方便。（我的20寸显示器不方便带到床上去，而且我也不喜欢去读400页的印刷品。）除此之外，我买这个软件花了395美元，而你给我的是89美分的塑料？真的！
A dead-tree manual necessary to the use of the program is the ultimate piracy-defeater. Pirates will blissfully copy your CD-ROM, they will blissfully upload your code to the newsgroups, but they won‘t Xerox the manual. It‘s not that they can‘t; they just won‘t. If you scrimp on the manual, you may still retain market share, but you won‘t be selling a lot of software.
程序使用所必需的dead-tree手册是最大的盗版抵抗者。盗版者将会开心的拷贝你的光盘，会开心的向新闻组中上传你的代码，但是他们不会复印手册。不是他们不能；而是他们不愿意。如果你在手册上吝啬，你仍然可以保留市场占有率，但是无法卖出很多的软件。
Some folks have found a clever way to drive people to piracy even while supplying a dead-tree manual. We now have the spectacle of major software houses, including Microsoft and Apple, turning out atrocious manuals in the full expectation that users will buy "real" manuals in the bookstore, so the users can actually figure out how to use the program. These manufacturer‘s junk manuals typically display the characteristics of an edited feature spec, with no thought as to structure. (Sometimes the features are just listed in alphabetical order!)
一些人已经发现了一个聪明的方式去盗版带有dead-tree手册的软件。我们现在有像微软和苹果这样的专业软件公司做参照，假设手册都变成了糟糕的形式，那么用户将去书店中购买“真正的”手册，可以切实的指导用户怎么去使用这个软件。这些制造商的手册是拆分的，一个手册可能只是讲解一个编辑功能，不需要考虑框架。（有时功能会以字母顺序排列！）
What a great technique for inspiring piracy: Anger users with a stupid, useless, paper manual they may spend days failing to understand, then force them spend lots of additional money buying a lucid, third-party manual. These people‘s advice to others? "Steal the software and spend your money instead on this really great manual I found down at the bookstore."
这对于鼓励盗版是多么好的技术：用户可能花费数天都不能理解这份愚蠢的、没用的纸质手册，难怪会生气。这迫使他们去花许多额外的钱购买清楚的、第三方的手册。这些人怎么建议其他人？软件就用盗版的吧，把钱留着去买我在书店中找到的真正好的手册。
Conflict Catcher 8 comes with two manuals—one where you learn about the program and one other really skinny one you use when your system has gotten in trouble and you are using Conflict Catcher to help straighten it out. Both are complete, both are lucid, both are all you will ever need to use the program, and both are essential.
Conflict Catcher 8带有两份手册—一份用来了解软件；当你的系统出现问题，需要使用Conflict Catcher帮你找到问题的时候需要使用另一份手册。两份手册都是完整地、清晰的，在使用软件过程中都是需要用到的，而且是很重要的。
2) Explain the problem being solved
2）解释被解决的问题
A lot of bad manuals out there are actually good feature specs that companies have just translated from engineeringese into a human language, then shipped. The problem with this approach is that you end up with a manual that explains every feature in depth, while keeping secret why anyone would ever want to use them.
大多糟糕的用户手册其实也有好的方面，就是公司已经将专业术语转变为通俗的语言。但它仍然有问题，就是止于深入的解释每一个功能，而没有说明为什么需要这个功能。
Programming language manuals are almost universal in this failing. They present 100 or 200 different commands without once mentioning what they are useful for. The human mind doesn‘t work from disembodied specs. Humans find it extremely difficult to store free-floating information. Explain a problem and offer a solution and people will remember it forever. Jump right to the solution, without ever presenting the problem, and it just won‘t penetrate.
编程语言手册几乎普遍都是失败在这个原因上。它们展示了100或200条不同的命令，却没有一条提到它们用来做什么。人类的思想在无形的规格下是无法运转的。人类发现存储无根据的信息是极其困难的。如果你解释一个问题并提供对应的解决方法，人们会永远记住的。直接跳到解决方案，而不解释问题的提出，人们将无法理解。
Let‘s examine this shortened excerpt from David Pogue‘s Conflict Catcher 8 manual on the subject of building a new system folder:
让我们看看从David Pogue的Conflict Catcher 8手册中关于构建一个新的系统文件夹部分的摘录：
One of the most important troubleshooting tools is the clean system install—which means giving your Macintosh a brand-new system folder, straight off your Mac‘s original CD….Your new system folder is guaranteed to be free [of] corruption. Unfortunately, it‘s also guaranteed to be free of any useful enhancements….Before Conflict Catcher 8, the final step in the clean system install process was the tedious business of comparing, side-by-side, the contents of your old system folder with the contents of your new one….Only after you had performed this time-consuming comparison would your Mac be ready to go….Fortunately, Conflict Catcher 8 greatly simplifies and accelerates this…process.
Troubleshooting tool的一个最重要的功能是清理系统安装—就是给你的苹果电脑一个全新的系统文件夹，直接来自你的Mac原版CD。新的系统文件夹是受保护的。不幸的是，它还保证了没有任何有用的增强。在Conflict Catcher 8之前，清理系统安装过程的最后一步是冗长乏味的比较，并行的比较旧系统文件夹和新系统文件夹。只有在执行完这个冗长的比较过程之后你的Mac才能运行。幸运的是，Conflict Catcher 8极大地简化和加快了这一过程。
By the time the user has finished reading the original five paragraphs from which this is drawn, they understand why they would want to do a clean install in the first place, what problem arises because of a clean install, and what Conflict Catcher 8 is prepared to do about it.
当用户读完原文中的五段话后，他们就明白为什么第一步要清理安装，清理安装会引发什么问题，Conflict Catcher 8是怎么处理的。
David goes one step beyond, however, by "selling" the product. That might seem silly, since obviously the person has already bought the product. However, when the reader understands that Conflict Catcher is going to eliminate for them a task that traditionally took three to four hours of the most boring, tedious work imaginable, they are going to get excited. Excited enough to tell their friends about Conflict Catcher. Excited enough even to write an article about it.
David通过“卖”产品，对其进一步的提升。这看起来似乎没头没脑，因为明显的人们已经购买了产品。然而，当读者明白Conflict Catcher将会为他们排除原来预计需要花费三到四个小时的枯燥的、冗长乏味的工作时，他们将会非常兴奋。兴奋到把Conflict Catcher告诉他们的朋友。兴奋到写一篇关于Conflict Catcher的文章。
Users now understand the motivation for the feature, as well of the value of the feature. Their minds have become fertile ground for the explanation of how to use the feature. A single reading will now transfer better than five readings would have in the absence of this understanding.
用户现在明白了这个功能的动机，以及这个功能的价值。他们的想法变成了解释如何使用这个功能的肥沃的土壤。一个的阅读将比五次不理解的阅读更加有意义。
3) Present the concepts, not just the features.
3）不只介绍功能，还要介绍概念
Well-designed software should be centered on a few, large concepts. HyperCard, Bill Atkinson‘s hypertext forerunner to the browser, had a single, underlying concept. Get that, and you got HyperCard. Miss it, and you were lost. The concept centered on layering, with both the background object, the "card," and objects place on the card each having several specialized layers.
设计好的软件应该集中于几个大的概念。HyperCard，作为浏览器先驱的Bill Atkinson的超文本，有一个单一的、基础的概念。了解它，你就理解了HyperCard。没有它，你就迷失了。这个概念就是分层，背景对象（card）和card上的对象都有几个指定的层。
The HyperCard manual began with an exploded diagram of the layers. That single illustration meant the difference between the user quickly grasping the application and the user floundering around for days and days, trying to build up that same concept from bits and pieces of information scattered about the application and manual.
HyperCard手册以一个层的展开图表开始。这个唯一的插图展示了快速掌握应用的用户与花费数天的时间挣扎着试图通过零散的信息块构建相同的概念的用户之间的不同。
Any time you learn a new piece of software, you go through the process of constructing a mental model of the software, what Don Norman calls the "User Model." Building a model requires a framework, and the framework consists of these large, key concepts. Without a framework, it is extremely difficult to learn.
无论何时，学习一个新的软件，首先都需要建立一个关于这个软件的心理模型，Don Norman叫做用户模型。构建心理模型需要一个框架，这个框架由几个大的、关键的概念构成。如果没有框架，将很难学习这个软件。
The designers gradually work toward these concepts as they experiment with the program. Because of this, they have often internalized the concepts so thoroughly that they may not even be consciously aware of them. That‘s why manuals written from specs are usually impossible to learn from. The key concepts are entirely absent, so the user has nothing upon which to hang the bits and pieces of knowledge offered. Instead, they kind of float around in a cloud until the poor reader finally sees the pattern.
设计师按部就班的围绕这些概念尝试着处理这个问题。因此，他们往往将这些概念内化的非常彻底，他们可能都没有意识到。这就是为什么规格说明书通常不可能用来学习。关键概念完全不存在，因此用户无法将零碎的知识整合起来。相反的，他们在终于看到图案之前都是漂浮在云端的感觉。
When a user does finally "get it," the bits and pieces do not then suddenly coalesce; that‘s not the way our memory works. Most of the bits and pieces, with nothing to hang themselves on, will have drifted off forever. The user must now re-read the entire manual, finally tying the bits and pieces in place on their new-found framework.
当用户终于明白了框架，零零碎碎的知识也不会突然凝聚；那不是我们记忆的工作方式。大部分的碎片无法整合，将永远偏离。用户必须重新阅读整个手册，最终将碎片放到他们新发现的框架中。
Manual writers will not themselves "get it" when they first start hammering on a new application. And I‘ve even read manuals where the writer never did get it, either through lack of trying, lack of interest, or serious lack of ability. These manuals are useless.
手册作者在第一次开始处理一个新的应用时，自己也不明白框架。我甚至读到过作者完全不明白框架的手册，要么努力不够，缺乏兴趣，要么严重缺乏能力。这些手册是没用的。
Manual writers must be introspective. They must be aware as the "aha!" experiences that signal an incoming concept. They must then write that concept down and present it early enough to their readers that the readers don‘t have to go through the same struggle. That is the very essence of manual writing.
手册作者必须反思。他们必须意识到“啊哈！”，必须明白基本框架。然后他们必须把概念写下来并尽早的展示给读者。这样他们不必经历同样的挣扎。这是编写手册的本质。
The job becomes doubly difficult when you have already internalized the concepts, either because you are a member of the development team or are already thoroughly familiar with the application. That is another reason I was so impressed with Pogue‘s Conflict Catcher 8 manual, because I happen to know David entered the project with way too much foreknowledge to experience any "aha"s at all. It requires a consummate writer to be able to distill and present the key concepts under such conditions.
你要是将概念内化，工作将变得加倍困难，或者是因为你是开发小组的成员，或是你已经彻底熟悉了应用。我对Pogue的Conflict Catcher 8手册如此印象深刻的另一个原因，因为我知道David很早就加入项目，对项目非常的了解。在这种情况下，需要一个完美的作家才能够提取和展示关键概念。
4) Give ‘em more than they deserve
4）提出超出用户期望的内容
Manuals need to cover the task domain, not just the operation of the program. That doesn‘t mean that a tax planner manual needs to cover the entirety of tax law. The depth and extent of the task domain that must be presented will depend on a number of factors, including the expected domain knowledge of the users and the amount of knowledge necessary for people to be able to use the application.
手册不能只是介绍软件的操作，还应覆盖任务领域。这不是说税务策划手册需要包含完整的税法。需要展示的任务领域的深度与广度需要依赖于几个要素，包括用户应该具备的专业知识及使用软件应具备的知识量。
Expected knowledge of users
用户应该具备的专知识
Writers (and marketers) tend to underestimate this. One of the great miracles of personal computers is that they offer a path for people to increase their knowledge and skill on their own. Extremely complex "professional" applications, such as Adobe Photoshop, have millions of users who never set foot in a design class. They have learned from their peers, they have learned on their own, and they have learned from reading the excellent Photoshop manuals. Write a manual that excludes everyone but existing experts and you will seriously impact your volume of sales.
作者（和市场人员）往往低估了这。个人电脑的一个奇迹是，他们为人们提供了一个可以自己增长知识和技能的路径。极其复杂的“专业”应用，如Adobe PS图象处理软件，有数百万从来没有涉足过设计课程的用户。他们向同龄人学习，自学，通过阅读优秀的PS手册学习。一个只能给专家看的手册将会严重影响销售量。
Amount of domain knowledge necessary to use the application
使用应用所必需的知识量
Conflict Catcher is a fairly simple application designed to act upon and maintain the most complex and invisible part of the Macintosh OS. The folks at Casady & Greene realized this early-on and have always offered a pair of products, boxed together, to deal with it. One of those products is the Conflict Catcher application. The other is the manual. Each is a valuable and vital tool for the Macintosh user. Together they are even better.
Conflict Catcher是一个非常简单的应用，被设计成用来处理和维护苹果操作系统中最复杂和不可见的部分。在Casady和Greene意识到之前，总是提供用盒子装载一起的两个产品来解决这个问题。其中一个产品就是Conflict Catcher。另一个是手动的。每一个对于苹果用户都是有价值的重要的工具。一起使用更好。
Perhaps 75% of the Conflict Catcher manual is devoted to an in-depth explanation of how Macintosh extensions work. True, it would be difficult for the user to apply Conflict Catcher in the absence of such knowledge, but I‘ve seen a lot of companies, faced with a similarly obvious need, completely ignore it.
Conflict Catcher手册中的大概75%的内容都致力于深入解释苹果插件是怎么工作的。真的，如果没有这种知识，用户将难以使用Conflict Catcher。但是我见过很多企业，面对一个类似明显的需要，却完全的忽视掉。
The depth and extent of this domain knowledge presented in Conflict Catcher is impressive. Conflict Catcher users, having absorbed this manual, are fully able to maintain and repair their system extensions without the Conflict Catcher application at all! It is just slower and more tedious.
Conflict Catcher在知识领域的深度和广度的展示令人印象深刻。Conflict Catcher的用户，完全被手册吸引，完全能够在没有Conflict Catcher应用的情况下维护和修理他们的系统插件！那是缓慢且乏味的。
5) Make it enjoyable to read
5）使它读起来有趣
One key concept, centered on what Macintosh extensions are and why they cause trouble, underlies all of Conflict Catcher. Let‘s see how two different writers present it:
一个关键的概念，关于苹果电脑的插件是什么，以及为什么它们会引发问题，在Conflict Catcher的所有版本中都有介绍。让我们看看两个不同的作者分别是怎么描述的：
From the Conflict Catcher 4 manual:
Conflict Catcher 4的手册中是这样写的：
Since you first began using your Macintosh, you‘ve probably extended the services that it provides on more than one occasion to keep pace with your changing needs….All these seemingly unrelated changes have one important thing in common—the addition of specialized files to your system to make new services available….This growth has created…the need to be able to troubleshoot problems they can cause by interacting with one another or other parts of the system.
“当你第一次使用苹果电脑时，你可能已经扩展了很多服务，这些服务用于满足你在多种场合下的需要。这些看起来没什么关系的改变有一个重要的共同点—在你的系统中添加了额外的文件以便新服务的可用。这种增长也导致了更多的故障，可能是由它们之间的相互作用引起的，也可能由系统的其他部分引发。”
This is clear and competent, but consider David Pogue‘s introduction, in the Conflict Catcher 8 manual, of the same concept:
这段话也是足够清楚的。不过再来看看David Pogue在Conflict Catcher 8的用户手册中是怎么描述同一个概念的：
"Your Mac‘s software is the result of an accidental collaboration among hundreds of programmers."
“你的苹果软件是数以百计的程序员偶然的协作的结果。”
Now, that‘s great writing.
这是非常棒的写法。
In Conflict Catcher, the process of discovering a bad extension is a collaboration between the application and the user, with the application carrying out a series of experiments and the user reporting the results. In version 4, the manual carried this warning:
在Conflict Catcher中，应用程序和用户合作发现一个问题插件，应用程序会执行一系列的测试，然后用户报告问题。在版本4中，手册有这样的警告：
"It‘s extremely important to answer this question accurately, so, if there‘s any doubt in your mind, repeat the test and double check—it does‘t take much extra time and it ensures that the results of your test will be accurate.
“准确的回答问题是非常重要的，因此，如果你有任何的疑虑，重复的进行测试和检查—这不会花费太多额外的时间，它将会确保你的测试结果是精确的。”
David Pogue‘s handling:
David Pogue的处理：
"If, when Conflict Catcher asks you whether or not the problem is still around, you deliberately lie, then you deserve what you get. But, if you answered the question incorrectly by accident, keep in mind you can "rewind" the conflict test without having to start over. Just…."
“如果Conflict Catcher问你这个问题是否仍然发生的时候，你故意撒谎，那么你将得到你应得的。但是，如果你只是意外的错误的回答了问题，记住，你可以‘回退’冲突检测，而不需要重新开始。”
Both give you the information you need. David‘s is bedtime reading. The earlier manual is not.
都是提供你所需要的信息。David的适合睡前阅读。前面的手册不行。
Guidelines Summary
总结
For the perfect manual, follow one of these two procedures:
遵照下面的两个程序，可以得到完美的手册：
A) If you are a writer, write your manual using the following methodology:
A）如果你是一个作者，按照下面的方法编写手册：
1) Supply a (real) manual.
1）提供一份（真正的）手册
2) Explain the problem being solved
2）解释被解决的问题
3) Present the concepts, not just the features.
3）不止介绍功能，还要介绍概念
4) Give ‘em more than they deserve
4）提出超出用户期望的内容
5) Make it enjoyable to read
5）使它读起来有趣
B) If you need to hire a writer, hire David Pogue
B）如果你需要雇佣一个作者，就雇David Pogue
A few substitutes do exist. Look through the supplemental manuals for sale in the book stores. Find out who among the authors can write. Contact them and offer them immense sums of money. It will be a good investment.
若干个替代品是存在的。通过书店中出售的补充手册寻找。找到作者中可以担任的作者。联系他们，并提供巨大的金额。这是一个非常好的投资。
If you are hiring full-time writers, ask for samples of their non-technical writing, as well as their technical writing. It has been my experience that real writers write because they are compelled to, not because they are being paid. Most technical writers who have never otherwise written cannot otherwise write. (I‘m sure exceptions exist.)
如果你要雇用全职写手，看下他们的非技术性的作品样本，以及他们的技术性作品。据我的经验，真正的作家是被迫写作的，而不是因为他们的报酬。大多数的技术作家不得不写。（我敢肯定也存在例外。）
Actually read what they supply in the way of technical writing samples. Can you understand it? If not, why not? Is it because it is covering an area so complex and so arcane that you, a mere mortal, could not be expected to understand it? Or is it because the writer just regurgitated specs, instead of exposing the concepts and taking on the tough job of really training the users?
实际上，读他们提供的技术性作品样本。你能理解吗？如果不能，为什么呢？是因为它包含对你来说复杂而神秘的内容吗？不能期待一个凡人可以理解它吗？或者是因为作者只是依样复述规格，而不是展开概念并以真正地培训用户为目的？
Superb writers are out there. They can be found. There are no excuses.
高超的作家是有的，他们可以被找到，没有任何理由。
说明：
1、文档对于程序员来说是很重要的，也是经常被忽略的。一份好的用户手册会给我们的软件增色不少，希望这篇文章可以给大家一些启发。
2、文章没有完全按照原文翻译，有些改成了更通俗的方式。
3、有些地方不太明白，所以可能有一些不太通顺的地方。例如：dead-tree manual，不知道怎么翻译好。
4、欢迎大家对于翻译不好的地方，提出更加合适的翻译方式。
csdn中的地址：http://blog.csdn.net/doris_d/article/details/42527145
标签：
原文地址：http://www.cnblogs.com/hibernation/p/4234919.html
