Um FAQ (Frequently Asked Questions, que traduzido significa “perguntas feitas freqüentemente”) ruim é um que não é composto de questões que as pessoas realmente perguntaram, mas de questões que o autor do FAQ desejou que as pessoas tivessem perguntado. Talvez você já viu esse tipo de pergunta antes:

O problema com tais FAQs é que eles não são, em um sentido literal, FAQs de verdade. Ninguém jamais telefonou para o suporte técnico e perguntou: “Como nós podemos maximizar a produtividade?”. Ao invés disso, as pessoas fazem questões altamente específicas como: “Como nós podemos mudar o sistema de calendário para enviar lembretes dois dias antes ao invés de um?”, e assim por diante. Mas é muito mais fácil produzir FAQs imaginários do que descobrir os reais. Compilar um verdadeiro FAQ requer um esforço contínuo e organizado: durante o tempo de vida do software, as questões que chegam devem ser rastreadas, respostas devem ser monitoradas, e tudo deve ser reunido em um todo coerente e pesquisável que reflete a experiência coletiva de usuários na vida real. São necessárias a paciência e a atitude observadora de um pescador. Nenhuma grande teoria, nenhum pronunciamento visionário aqui—olhos abertos e registros precisos são as coisas mais necessárias.

O que eu mais gosto sobre este livro é que ele amadureceu justamente desse processo. É o resultado direto do encontro dos autores com os usuários. Começou com a observação de Ben Collins-Sussman de que as pessoas estavam perguntando as mesmas questões básicas repetidamente nas listas de discussão do Subversion: Quais são os procedimentos padrões para usar o Subversion? Branches e tags funcionam do mesmo jeito que em outros sistemas de controle de versão? Como posso descobrir quem fez uma determinada mudança?

Frustrado em ver as mesmas questões dia após dia, Ben trabalhou intensamente por um mês no verão de 2002 para escrever The Subversion Handbook, um manual de sessenta páginas que cobria todos os conceitos básicos para usar o Subversion. O manual não tinha pretensão de ser completo, mas foi distribuído com o Subversion e levou os usuários além daquele início da curva de aprendizado. Quando a O'Reilly and Associates decidiu publicar o primeiro livro completo sobre Subversion, o jeito mais fácil era óbvio: apenas expandir o handbook do Subversion.

Os três co-autores do novo livro estavam encarando uma oportunidade incomum. Oficialmente, a sua tarefa era escrever um livro no estilo top-down, começando de um índice e de um rascunho inicial. Mas eles também tiveram acesso a uma torrente—na verdade, um géiser incontrolável—de material do tipo bottom-up. O Subversion já estava nas mãos de milhares de antigos adeptos, e esses usuários estavam dando toneladas de feedback, não apenas sobre o Subversion, mas sobre sua documentação existente.

Durante todo o tempo que eles escreveram este livro, Ben, Mike e Brian freqüentaram incessantemente as listas de discussão e salas de bate-papo do Subversion, cuidadosamente notando os problemas que os usuários estavam tendo em situações da vida real. Monitorar tal feedback é algo que está na descrição da função que eles têm na CollabNet, o que deu a eles uma enorme vantagem quando eles se prepararam para começar a documentar o Subversion. O livro que eles produziram está firmemente fundado na rocha da experiência, não nas areias movediças da fantasia. Ele combina os melhores aspectos de manual de usuário e FAQ. Essa dualidade pode não ser notada na primeira leitura. Se lido em ordem, do início ao fim, o livro é simplesmente uma descrição direta de um pedaço de software. Há uma visão geral, o tour obrigatório, o capítulo sobre configuração administrativa, alguns tópicos avançados, e, claro, uma referência de comandos e um guia para resolução de problemas. Apenas quando você volta mais tarde procurando a solução para um problema específico, a sua autenticidade então aparece: os detalhes reveladores que só podem resultar de um encontro com o inesperado, os exemplos afiados de genuínos casos de uso, e, mais do que tudo, a sensibilidade às necessidades do usuário e o ponto de vista do usuário.

Claro, ninguém pode prometer que este livro responderá a todas as questões que você tiver sobre Subversion. Algumas vezes, a precisão com que ele antecipa as suas questões parecerá assustadoramente telepática; ainda que ocasionalmente, você tropeçará em um buraco no conhecimento da comunidade, e sairá com as mãos vazias. Quando isso acontecer, a melhor coisa a fazer é enviar um e-mail para <users@subversion.tigris.org> e apresentar o seu problema. Os autores ainda estão lá, ainda observando, e eles incluem não apenas os três listados na capa, mas muitos outros que contribuíram com correções e material original. Do ponto de vista da comunidade, resolver o seu problema é meramente um agradável efeito colateral de um projeto muito maior—que é ajustar este livro lentamente, e o próprio Subversion em última instância, para corresponder cada vez mais com o modo que as pessoas atualmente usam ele. Eles estão ansiosos para ouvir de você, não meramente porque eles podem ajudá-lo, mas porque você pode ajudá-los. Assim como em qualquer outro projeto de software livre, você não está sozinho com Subversion.

Deixe este livro ser a sua principal companhia.

— Karl Fogel, Chicago, 14 de Março de 2004.