Viver o futuro da escrita técnica

As aventuras surpreendentes e a ferramenta final do Pro Git, 2ª edição

Quase exatamente seis anos atrás, fui abordado pela Apress para ajudar em um livro que estava sendo escrito, mas estava atrasado, chamado Pro Git. Eventualmente, o autor original decidiu não continuar escrevendo e reescrevi o livro a partir do zero, sendo finalmente publicado em agosto de 2009. Para os três primeiros capítulos, escrevi o livro no Word, enviando documentos para o meu editor e recuperando versões redline algum tempo depois.

Depois de cerca de três capítulos, eu estava prestes a desistir quando sugeri que mudássemos para fazer o livro em Markdown para a fase de redação e edição técnica e, em seguida, voltei para o Word apenas para a edição de cópias, que foi acordado. Uma vez que o livro foi concluído, voltei a mover todo o conteúdo para o Markdown para que eu pudesse publicá-lo online em um site que criei. Por sorte, para mim, o autor original conseguiu que a Apress concordasse com a licença Creative Commons, o trabalho também.

Mais de um ano depois, a Apress também lançou uma versão Kindle do livro, embora as pessoas tenham produzido versões compatíveis com Kindle a partir do conteúdo de código aberto, assim que o livro foi lançado.

Pro Git, segunda edição

Uma vez que o livro foi razoavelmente bom, depois de cerca de quatro anos de impressão, a Apress me aproximou para fazer outra edição do livro. No decorrer desse tempo, minha empresa GitHub passou de ser 4 pessoas trabalhando em um site para alguns milhares de usuários para uma gigantesca presença on-line hospedando milhões de repositórios e empregando mais de 200 pessoas. Não só a comunidade GitHub mudou tanto, mas a própria ferramenta também teve algumas mudanças significativas. Eu concordei que provavelmente era hora de renovar o conteúdo.

Enquanto você agora pode ler a segunda edição (assim como a primeira edição) online ou baixá-la em formatos PDF, ePub ou Mobi (Kindle) para ler seu dispositivo favorito, pensei que uma história interessante para compartilhar seria a diferença em como Esta versão foi produzida a partir da primeira versão há cerca de cinco anos.

A Escrita do Pro Git v2

Eu realmente tinha começado a renovar o Pro Git algumas vezes nos últimos anos. Principalmente eu estava interessado nos aspectos da cadeia de ferramentas. Em algum momento eu comecei um projeto chamado Git Scribe, que pretendia demonstrar o tipo de ferramenta que eu desejava que eu pudesse usar para escrever o Pro Git. A ferramenta Scribe forneceu uma maneira semi-fácil de instalar uma cadeia de ferramentas que levaria um livro Asciidoc formatado especificamente e produziria livros legais de HTML, PDF, ePub e Mobi bonitos. Embora o projeto tenha morrido desde então e acabamos usando a plataforma Atlas da O'Reilly, o projeto Scribe me levou a Asciidoc em primeiro lugar.

Asciidoc

Então troquei grandes porções do Pro Git para o Asciidoc. O problema com a Markdown foi que era muito simples. Não especificou coisas como formatação de tabela, referências cruzadas, indexação, referências, exemplos de código-fonte, etc. Tudo o que a Asciidoc faz em um formato que é tão fácil de escrever.

Então, mudei tudo de Markdown para o Asciidoc e notei que algumas editoras também estavam fazendo isso. O'Reilly começou a permitir que os livros fossem escritos em Asciidoc, pois ele genera o Docbook facilmente e acredito que os Programadores Pragmatic usaram uma linguagem de marcação simples por um tempo antes disso.

O mais importante para tudo isso foi o surgimento do Asciidoctor. Quando eu fui refazer o meu site do Git (git-scm.com), eu queria levar as fontes da página de manicômio do Asciidoc para o Git e fazer boas versões on-line deles e queria fazê-lo com o Ruby. Meu amigo e colega de trabalho da GitHub, Nick Hengeveld, escreveram um bom analisador e formatador para o Asciidoc para ajudar a fazer isso. Eventualmente, alguns outros GitHubbers (Ryan Waldron e Jeremy McAnally) se juntaram e transformaram Asciidoc.rb em Asciidoctor, que acabou sendo assumido pelo incrível Dan Allen, que levou o projeto a um nível totalmente novo.

Agora que o Asciidoctor está por perto, posso fazer coisas realmente incríveis com meu livro de fontes Asciidoc que não eram tão simples antes.

GitHub

Uma das maiores mudanças no fluxo de trabalho de escrita foi que o GitHub está muito melhor agora do que antes. Agora, tivemos solicitações de pull para revisão e comentários, emitem marcos para o planejamento de capítulos, prosa diffs para uma revisão mais fácil e verificação local, e o editor de texto Atom para escrita e pré-visualização de Asciidoc.

O fluxo de trabalho que temos que usar é que todos os que já escreveram um livro técnico, especialmente com um co-autor, provavelmente estarão com inveja de inveja.

Nós escrevemos tudo o que queríamos fazer, adicionou todos os pontos principais como questões associadas a marcos para cada capítulo e então cada um decidiu o que íamos fazer e começamos a escrever. Poderíamos fazer um ramo para a unidade de trabalho que estávamos fazendo (normalmente um capítulo) e começar a escrever e empurrar para o ramo GitHub. Nós falamos em Slack e recebemos atualizações instantâneas sempre que um de nós empurrou alguma mudança. Abrimos um Pedido de Puxo quase que imediatamente, geralmente com uma lista de verificação de coisas que queríamos completar antes da fusão, para que você pudesse saber qual era o status de cada ramo ( exemplo ).

Quando uma filial funcionou por muito tempo, poderíamos juntar o ramo mestre para mantê-lo atualizado e garantir que os conflitos nunca foram um grande problema, mesmo através de mudanças estruturais maciças, como dividir capítulos em vários arquivos.

A revisão foi feita através dos pedidos de tração – podemos deixar comentários em qualquer linha de texto introduzido e conversar lá ou conversar sobre isso.

Posso instalar o plugin de pré-visualização do Asciidoc Atom e obter visualizações renderizadas ao vivo do texto que escrevi enquanto escrevê-lo, incluindo dicas de barra lateral sobre o que eu acrescentei, modificava ou excluía, em qual ramo estava, mesclava ferramentas de ajuda de conflito , modo zen, etc. Foi um ambiente de escrita incrível.

Não só isso, mas fizemos a maior parte dessa colaboração enquanto 9 zonas horárias se separavam e nosso editor poderia, a qualquer momento, olhar para a página dos milênios para ver o que nosso progresso era através do livro.

Se você escreveu um livro técnico e não o fez em Asciidoc no GitHub moderno, você fez dez vezes mais trabalho do que você precisava.

Atlas

Não só escreveu e colaborou no livro, mais fácil do que na primeira edição, mas ver como ficaria infinitamente mais fácil.

O sistema de compilação O'Reilly Atlas. Aponte e clique em ebooks bonitos em minutos.

Graças, em parte, às conversas que tive com Tim O'Reilly, Laura Baldwin e outras pessoas na O'Reilly Media, há anos atrás sobre o quanto melhor esta ferramenta poderia ser, fui convidado a experimentar a plataforma que estavam desenvolvendo para facilitar tudo. . Todos concordamos em quão genial seria passar de escrever em Asciidoc para 'empurrar git' para PDF. Eles acabaram criando e felizmente eles me deixaram experimentar.

Você pode me ver sendo bastante ativo no seu fórum por vários meses e sempre que mencionei algo que eles tinham consertado em dias ou até horas. Não só isso, mas as compilações produziram resultados tão bonitos que, para as revisões dos capítulos, acabei por criar um PDF, baixá-lo e lê-lo no Preview enquanto faz anotações e mudanças na fonte Asciidoc.

Felizmente, eles também têm uma API para o serviço e você pode criar diferentes ramos separadamente. Isso significa que eu consegui escrever um serviço que escuta ganchos pós-recebimento no repositório Pro Git, puxa as mudanças, empurra-as para o Atlas e inicia automaticamente uma compilação. Ele então pesquisa para quando todas as compilações são feitas e as move para o meu próprio balde AWS S3 e atualiza o novo site progit.org e o conteúdo e os links do site git-scm.com.

Não só isso, mas eu posso fazer isso para todos os idiomas em que o Pro Git está traduzido. Isso significa que, no futuro próximo, se você for para o site Pro Git ou o site git-scm.com , você pode baixar ebooks de nível profissional em qualquer formato da versão mais recente do Pro Git a partir de minutos após a última errata fundir. Em qualquer idioma. Com zero trabalho de mim ou os mantenedores da linguagem depois de acertar o botão 'mesclar'.

Eu basicamente agora tenho a configuração de distribuição e distribuição de ebook multi-linguagem mais simples e sofisticada no planeta.

Código aberto

Outra diferença interessante entre a primeira e segunda edições é que, como não queria passar pelo processo Markdown to Word para Markdown novamente, concordamos em poder escrever o livro na sua totalidade e depois "jogá-lo sobre o muro" para Apress que faria a conversão do Word e a edição da cópia e depois nos enviaria as mudanças. Isso significa que Ben e eu conseguimos abrir o livro muito mais cedo no processo do que antes.

Atualmente, o livro está totalmente disponível on-line , incluindo em todos os formatos de ebook, mas ainda está provavelmente a meses de impressão. Neste momento, temos a certeza de obter uma tonelada de edições de pequenas cópias e correções técnicas (já recebemos um punhado nas primeiras 24 horas) e poderemos juntá-las antes que Apress vá imprimir. Isso significa que podemos encontrar e corrigir erratas antes de imprimir o livro, o que é bastante surpreendente.

Nós realmente debatimos escrevendo todo o livro ao ar livre ou esperando até que ele estivesse principalmente completo antes de reabri-lo. No final, optamos pelo último, embora ainda não tenha certeza de que o primeiro não teria sido a melhor opção. Nós achamos que pode ser muito incômodo para lidar com opiniões de toda a comunidade durante todo o processo e que preferimos possuir o conteúdo um pouco mais fundamentalmente, mas pode ter sido interessante ter passado a outra rota. Talvez da próxima vez.

Traduções

A última coisa que é dramaticamente diferente desta vez é o tratamento das traduções do trabalho. Quando abrir sourcing na primeira edição, não me lembro de pensar em traduções. Não lembro de ter obtido o meu primeiro trabalho traduzido, mas teve que ter sido bastante rápido depois que eu o soltei porque reestruturei os diretórios para colocar tudo em um diretório 'en' pouco depois do lançamento.

Nos cinco anos em que o livro foi lançado, foi totalmente traduzido para pelo menos 10 línguas e parcialmente traduzido para provavelmente outro ( Deutsch, ?? ??, ? ? ??, Français, ???, Nederlands, ???????, ???, Português e ?eština ). 20. Uma vez que eu decidi armazená-los em subdiretórios do repositório principal e peguei pedidos de tração para eles, isso significava que alguém que tivesse acesso de gravação ao repositório teve que mesclá-los. O que significava que eu basicamente tinha que combinar tudo, mesmo que eu não consiga ler quase nenhum desses idiomas. Eventualmente, depois de alguns anos, fiquei muito mal por manter os pedidos de retirada e o incrível Jean-Noël Avila assumiu e gerenciou as traduções (e até mesmo as erratas inglesas) desde então.

Desta vez, podemos aprender com os problemas que tivemos antes e tentar facilitar a todos. Desta vez, estamos fazendo de cada tradução um repositório separado sob a organização progit e adicionando mantenedores específicos do idioma para cada um. Isso significa que você pode abrir um problema na versão ZH em mandarim e não nos deixar totalmente confusos. Se os mantenedores deixam de responder e alguém está interessado, podemos adicioná-los como um novo mantenedor.

Graças ao Atlas, cada tradução também terá seu próprio processo de compilação automatizado em vez de fazer todos executarem suas próprias compilações localmente, como já foi o caso até agora.

Em suma

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *