（翻譯）如何編寫好的用戶手冊？

原文：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.

高超的做家是有的，他們能夠被找到，沒有任何理由。

 

說明：

一、文檔對於程序員來講是很重要的，也是常常被忽略的。一份好的用戶手冊會給咱們的軟件增色很多，但願這篇文章能夠給你們一些啓發。

二、文章沒有徹底按照原文翻譯，有些改爲了更通俗的方式。

三、有些地方不太明白，因此可能有一些不太通順的地方。例如：dead-tree manual，不知道怎麼翻譯好。

四、歡迎你們對於翻譯很差的地方，提出更加合適的翻譯方式。

 

CSDN中的地址：http://blog.csdn.net/doris_d/article/details/42527145