Premessa

A bad Frequently Asked Questions (FAQ) sheet is one that is composed not of the questions people actually asked, but of the questions the FAQ's author wished people had asked. Perhaps you've seen the type before:

Una pagina scadente delle domande frequenti (Frequently Asked Questions-FAQ) è quella composta non dalle domande che la gente veramente pone, ma da domande che l'autore di quella FAQ avrebbe voluto che fossero state poste. Forse avete già incontrato cose di questo tipo:

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, like, “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.

Il problema di queste FAQ è che non sono, in senso letterale, per nulla FAQ. Nessuno ha mai chiamato il supporto tecnico per chiedere: «Come possiamo massimizzare la produttività?». La gente, piuttosto, pone domande molto specifiche, tipo: «Come possiamo cambiare il sistema di calendario per spedire i promemoria con anticipo di due giorni invece di uno?» e via dicendo. Ma è molto più semplice costruire FAQ immaginarie che elaborarne una reale. Compilare una vera pagina delle FAQ richiede uno sforzo continuo ed organizzato: durante il ciclo di vita del software le domande pervenute devono essere tracciate, le risposte monitorate e tutto deve essere messo insieme in un modo coerente e consultabile, che rifletta l'esperienza collettiva di tutti gli utenti. È richiesta l'attitudine all'osservazione paziente propria di un naturalista. Non grandi ipotesi, non dichiarazioni visionarie—occhi aperti ed un accurato prender nota, è tutto quel che serve.

What I love about this book is that it grew out of just such a process, and shows it on every page. It is the direct result of the authors' encounters with users. It began with Ben Collins-Sussman's observation that people were asking the same basic questions over and over on the Subversion mailing lists: What are the standard workflows to use with Subversion? Do branches and tags work the same way as in other version control systems? How can I find out who made a particular change?

Quel che amo di questo libro è il fatto che sia cresciuto proprio da un processo di questo tipo e lo mostra in ogni pagina. Esso è il risultato diretto dell'incontro tra gli autori e gli utenti. È cominciato dall'osservazione di Ben Collins-Sussman che le persone ponevano sempre le stesse domande base nelle mailing list di Subversion: Quali sono i flussi di lavoro standard da usare con Subversion? Branch e tag funzionano come negli altri sistemi per il controllo di versione? Come posso scoprire chi ha fatto una particolare modifica?

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 sixty 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 and Associates decided to publish a full-length Subversion book, the path of least resistance was obvious: just expand the Subversion handbook.

Frustrato dal vedere sempre le stesse domande giorno dopo giorno, Ben ha lavorato intensamente per più di un mese nell'estate 2002 per scrivere The Subversion Handbook, manualetto di 60 pagine che copriva tutte le nozioni di base sull'uso di Subversion. Il manuale non pretendeva di essere completo, ma fu distribuito con Subversion ed ha dato agli utenti la spinta iniziale nella curva d'apprendimento. Quando O'Reilly and Associates hanno deciso di pubblicare un libro su Subversion in edizione completa, la via più facile era ovvia: semplicemente espandere Subversion handbook.

The three co-authors 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.

Ai tre co-autori del nuovo libro si è presentata un'opportunità non comune. Ufficialmente, loro compito era scrivere un libro 'top-down', cominciando dall'indice e da una bozza iniziale. Ma gli autori avevano anche accesso ad una massiccia corrente— davvero un geyser incontrollabile— di materiale originale di tipo 'bottom-up'. Subversion era già nelle mani di migliaia di utenti neofiti e questi fornivano tonnellate di feedback non solo riguardo Subversion ma anche riguardo la sua documentazione.

During the entire time they wrote this book, Ben, Mike, and Brian haunted the Subversion mailing lists and chat rooms incessantly, carefully noting the problems users were having in real-life situations. Monitoring such feedback is part of their job descriptions at CollabNet anyway, and it gave them a huge advantage when they set out to document Subversion. The book they produced is grounded firmly in the bedrock of experience, not in the shifting sands of wishful thinking; it combines the best aspects of user manual and FAQ sheet. This duality might not be noticeable on a first reading. Taken in order, front to back, the book is simply a straightforward description of a piece of software. There's the overview, the obligatory guided tour, the chapter on administrative configuration, some advanced topics, and of course a command reference and troubleshooting guide. Only when you come back to it later, seeking the solution to some specific problem, does its authenticity shine out: the telling details that can only result from encounters with the unexpected, the examples honed from genuine use cases, and most of all the sensitivity to the user's needs and the user's point of view.

Durante la stesura del libro, Ben, Mike e Brian hanno perlustrato senza sosta le mailing list e chat room di Subversion, annotando con cura quali problemi avevano gli utenti in situazioni reali. Monitorare assiduamente il feedback degli utenti è parte del loro lavoro presso CollabNet, e ciò li avvantaggiò molto quando si misero a documentare Subversion. Il libro che hanno prodotto è ancorato saldamente sulla roccia dell'esperienza, non sulle sabbie mobili dei desideri; esso combina gli aspetti migliori di un manuale per utenti e di una pagina delle FAQ. Questa dualità forse non si nota alla prima lettura. Preso in ordine, dalla prima al'ultima pagina, il libro è semplicemente una chiara descrizione di un software. Ci sono introduzione, l'obbligatoria 'visita guidata', il capitolo sulla configurazione, alcuni concetti avanzati e naturalmente, la dettagliata spiegazione delle opzioni dei comandi e la guida alla risoluzione dei problemi. Solo quando ci si torna in seguito, cercando la soluzione d'un particolare problema, salta fuori la sua autenticità: i dettagli parlanti che possono essere solo frutto di incontri con l'inaspettato, gli esempi affinati da casi d'uso genuini, e soprattutto la sensibilità ai bisogni degli utenti ed al loro punto di vista

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 <users@subversion.tigris.org> and present your problem. The authors are still there, still watching, and they 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 merely because they can help you, but because you can help them. With Subversion as with all active free software projects, you are not alone.

Certamente, nessuno può promettere che questo libro risponderà ad ogni domanda che si possa avere riguardo Subversion. Qualche volta, la precisione con cui anticipa le vostre domande potrà sembrare misteriosamente telepatica; ma alle volte ci si imbatte in una lacuna nel bagaglio di conoscenze della comunità e si torna a mani vuote. Quando succede, la cosa migliore è inviare una email a <users@subversion.tigris.org> ed esporre il proprio problema. Gli autori sono ancora lì, ancora osservano e non sono solo i tre citati sulla prima pagina, ma molti altri che hanno contribuito con correzioni e con nuovo materiale. Dal punto di vista della comunità, risolvere il vostro problema è solo il piacevole effetto collaterale di un progetto più ampio— cioè, pian piano sistemare questo libro, e alla fine Subversion stesso, per avvicinarsi di più al modo in cui la gente lo usa. Sono desiderosi di sentirvi non solo perché vi possono aiutare, ma perché voi potete aiutare loro. Con Subversion come nel caso di tutti i progetti attivi di software libero non siete soli.

Let this book be your first companion.

Che questo libro sia il vostro primo compagno.

— Karl Fogel, Chicago, 14 March, 2004