A bad Frequently Asked Questions (FAQ) sheet is one that is composed not of the questions people actually ask, but of the questions the FAQ's author wishes people would ask. Perhaps you've seen the type before:
A: Many of our customers want to know how they can maximize productivity through our patented office groupware innovations. The answer is simple. First, click on the
Filemenu, scroll down to
Increase Productivity, then…
The problem with such FAQs is that they are not, in a literal sense, FAQs at all. No one ever called the tech support line and asked, “How can we maximize productivity?”. Rather, people asked highly specific questions, such as “How can we change the calendaring system to send reminders two days in advance instead of one?” and so on. But it's a lot easier to make up imaginary Frequently Asked Questions than it is to discover the real ones. Compiling a true FAQ sheet requires a sustained, organized effort: over the lifetime of the software, incoming questions must be tracked, responses monitored, and all gathered into a coherent, searchable whole that reflects the collective experience of users in the wild. It calls for the patient, observant attitude of a field naturalist. No grand hypothesizing, no visionary pronouncements here—open eyes and accurate note-taking are what's needed most.
Frustrated at seeing the same questions day after day, Ben worked intensely over a month in the summer of 2002 to write The Subversion Handbook, a 60 page manual that covered all the basics of using Subversion. The manual made no pretense of being complete, but it was distributed with Subversion and got users over that initial hump in the learning curve. When O'Reilly decided to publish a full-length Subversion book, the path of least resistance was obvious: just expand the Subversion handbook.
The three coauthors of the new book were thus presented with an unusual opportunity. Officially, their task was to write a book top-down, starting from a table of contents and an initial draft. But they also had access to a steady stream—indeed, an uncontrollable geyser—of bottom-up source material. Subversion was already in the hands of thousands of early adopters, and those users were giving tons of feedback, not only about Subversion, but about its existing documentation.
在写这本书的过程里，Ben，Mike 和 Brian一直像鬼魂一样游荡在Subversion邮件列表和聊天室中，仔细的研究用户实际遇到的问题。监视这些反馈也是他们在CollabNet工作的一部分，这给他们撰写Subversion文档提供了巨大的便利。这本书建立在丰富的使用经验，而非在流沙般脆弱的想象之上，它结合了用户手册和FAQ的优点。初次阅读时，这种二元性的优势并不明显，按照顺序，从前到后，这本书只是简单的从头到尾描述了软件的细节。书中的内容包括一章概述，一章必不可少的快速指南，一章关于管理配置，一些高级主题，当然还包括命令参考手册和故障排除指南。而当你过一段时间之后，再次翻开本书查找一些特定问题的解决方案时，这种二元性才得以显现：这些生动的细节一定来自不可预测的实际用例的提炼，大多是源于用户的需要和视点。
Of course, no one can promise that this book will answer
every question you have about Subversion. Sometimes, the
precision with which it anticipates your questions will seem
eerily telepathic; yet occasionally, you will stumble into a
hole in the community's knowledge and come away empty-handed.
When this happens, the best thing you can do is email
<firstname.lastname@example.org> and present your
problem. The authors are still there and still watching, and the
authors include not just the three listed on the cover, but many others
who contributed corrections and original material. From the
community's point of view, solving your problem is merely a
pleasant side effect of a much larger project—namely,
slowly adjusting this book, and ultimately Subversion itself, to
more closely match the way people actually use it. They are
eager to hear from you, not only because they can help you, but
because you can help them. With Subversion, as with all active
free software projects, you are not