前言

Karl Fogel

芝加哥,2004年3月14日

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:

Q:怎样使用Glorbosoft XYZ最大程度的提高团队生产率?

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 File menu, 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.

我很喜欢这本书,因为它正是按照这种精神建立起来的,这种精神体现在本书的每一页中。这是作者与用户直接交流的结果。而这一切是源于Ben Collins-Sussman's对于Subversion常见问题邮件列表的研究。他发现人们总是在邮件列表中重复询问一些基本问题:使用subversion的一般程序是怎样的?分支与标签同其它版本控制系统的工作方式一样吗?我怎样知道某一处修改是谁做的?

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 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 alone.

让这本书将成为你的第一个伙伴。