Docs como Código em Linode

Olá! O meu nome é Nathan, e sou membro da equipe técnica de escrita da Linode. Um de nossos principais trabalhos é contribuir e manter a biblioteca de guias e tutoriais em https://www.linode.com/docs, onde mais de 1.400 artigos são publicados. A fim de manter a qualidade do conteúdo, e para incentivar a colaboração no processo de escrita, adotamos um documento como metodologia de código para nosso fluxo de trabalho de autoria.

Docs como código é uma metodologia onde as ferramentas utilizadas para escrever documentos são as mesmas que as ferramentas utilizadas para escrever software. Isto inclui:

• Usando o software de controle de versão
• Escrever artigos de documentação em texto simples
• Execução de testes automatizados
• Praticar a integração contínua e a entrega contínua

A equipe de redação técnica da Linode também ampliou esta metodologia, assumindo a responsabilidade pela infraestrutura da nuvem que hospeda o nosso site de documentos.

Porquê Docs como Código?

Seguir estas práticas oferece uma série de benefícios:

• Trabalhar com estas tecnologias ajuda a formar uma ligação mais estreita entre a equipe de redação técnica e as equipes de desenvolvimento e engenharia da Linode.
  
• Outras equipes da Linode podem contribuir para vários aspectos do nosso processo. Por exemplo: a equipe de finalização pode ajudar a atualizar a temática/apresentação para o site de docs usando as ferramentas com as quais já trabalham, e um membro da equipe de engenharia pode escrever novos testes automatizados para a biblioteca de docs.
  
• Nossa equipe frequentemente escreve guias e tutoriais sobre as tecnologias utilizadas em nosso processo. A implementação destes por nós mesmos nos dá uma melhor compreensão dos mesmos, o que melhora nossa capacidade de explicá-los.
  
• Também precisamos documentar os produtos da Linode com precisão, o que pode envolver a revisão da base de código da Linode. A fluência nas línguas e ferramentas utilizadas para estes projetos pode nos ajudar a compreendê-los melhor.

Nossa Implementação

Como as implementações desta metodologia podem variar entre diferentes organizações, eu gostaria de oferecer um esboço detalhado do nosso processo:

1. Autoria: Os nossos escritores técnicos são autores de novos guias em Markdown. Markdown é usado para representar texto rico em um arquivo de texto simples, e pode ser compilado em HTML por um conjunto de ferramentas. Markdown tem adoção quase universal no desenvolvimento de software; por exemplo, os arquivos GitHub README são escritos em Markdown. Escrever no Markdown também significa que você pode usar qualquer editor de texto simples que preferir, desde editores desktop modernos como Visual Studio Code, até Emacs e Vim. Sabemos que as pessoas têm opiniões fortes sobre seus editores de texto preferidos, e esta flexibilidade ajuda mais pessoas a contribuir para a nossa biblioteca.
   
2. Previsões Locais do Site: As pastas Markdown da nossa biblioteca são compilados na sua representação HTML final com um gerador de local estático. Sites estáticos são coleções de páginas pré-construídas que não dependem de um banco de dados para serem renderizadas quando solicitadas (como é o caso de um CMS como o WordPress). Por causa disso, um site estático é muito rápido de carregar. Um gerador de site estático torna um site estático ao combinar seus arquivos de conteúdo (por exemplo, Markdown) com um tema que você especifica.
   
   O website da Linode utiliza Hugoque é um dos mais populares geradores de sites estáticos:
   
   • Hugo oferece métodos de instalação bem documentados em muitos sistemas operacionais, por isso não há problemas ao embarcar um novo funcionário.
     
   • Hugo inclui um servidor web de desenvolvimento local, para que os autores possam renderizar o site em seus computadores enquanto escrevem novos guias. Este servidor também irá carregar direto sempre que o autor guardar a sua pasta.
     
   • Hugo é extremamente rápido, o que é um fator significativo para uma biblioteca do nosso tamanho - meu Macbook Pro é capaz de compilar todos os 1400 guias em aproximadamente 3 segundos, e a função de recarga ao vivo é quase instantânea. 
     
   • Os atalhos do Hugo também nos ajudam a melhorar nossos guias com recursos que Markdown não oferece, incluindo notas destacadas e trechos de código numerados por linha.
     
     
3. Colaboração: A biblioteca docs é armazenada em um repositório Git público hospedado no GitHub, e cada autor mantém um fork desse repositório. Quando um autor termina de redigir um guia, ele submete suas alterações, empurra as alterações até o fork e depois abre um pedido de puxar contra o repositório principal.
   
   Nosso processo de redação tem dois membros da equipe separados que realizam uma edição técnica e depois uma edição de cópia em quaisquer novos guias ou atualizações de guias. Estes membros da equipe farão o download da filial do pedido de puxar, farão e comprometerão suas mudanças, e então os empurrarão de volta para a filial no GitHub. Git é outra ferramenta quase universal para o desenvolvimento, e usá-la nos permite aproveitar algumas das melhores práticas padrão de colaboração, como o fluxo de trabalho de gitflow.
   
   Além disso, a popularidade do GitHub significa que ele tem um grande número de integrações úteis. Em particular, usamos o Netlify para gerar visualizações automáticas, acessíveis ao público, para cada pedido de puxar. Muitas vezes precisamos pedir feedback aos Linodians em diferentes departamentos, e eles podem ver esses links compartilháveis da Netlify sem ter que clonar nosso repositório de documentos e instalar Hugo em seus laptops.
   
   Finalmente, a hospedagem em um repositório público abre nossa biblioteca para colaboradores externos, que são bem-vindos.
   
4. Testando: Sempre que uma solicitação de puxar é submetida ou atualizada, uma série de testes são executados sobre o conteúdo do RP. Estes testes são realizados com Travis CI O GitHub é um serviço de integração contínua que também oferece a integração GitHub. Se algum destes testes falhar, então o pedido de puxar é temporariamente bloqueado para não ser fundido:
   
   • O conteúdo do guia é verificado desde a ortografia ao estilo (por exemplo, capitalização adequada dos termos técnicos). Usamos a Vale para realizar essas tarefas, que é um linter open-source que foi projetado para trabalhar em prosa. Quando integramos a Vale pela primeira vez, ela relatou mais de 500 mil erros ortográficos em nossa biblioteca. Embora um pouco vergonhoso, conhecer este número e depois ser capaz de agir sobre ele foi um grande impulso na confiança ao nosso conteúdo e ao nosso novo sistema editorial.
     
   • Nós verificamos se há potenciais links quebrados entre guias usando Scrapy, um framework Python de código aberto que verifica o conteúdo de sites. Este teste foi escrito em colaboração com um membro da equipe de engenharia da Linode. Quando implementamos o Scrapy pela primeira vez, encontramos, de forma semelhante, uma série de links quebrados que poderíamos corrigir.
     
   • Outro script Python verifica os metadados da matéria frontal para guias válidos e livres de erros de sintaxe. Uma seção de front-matter quebrada pode causar problemas na construção do site, por isso, ter isto validado significa que podemos ter a certeza de que o site irá render ao atualizar os servidores web de produção.
     
5. Publicação e Hospedagem: A atualização do site docs é tratada automaticamente por uma coleção de scripts que são acionados a partir de certos eventos no GitHub:
   
   • Sempre que o conteúdo é fundido no ramo principal do repositório principal de documentos, uma notificação de gancho da web é enviada para um servidor web de encenação, que é um Linode. Este servidor web de encenação então puxa o ramo mestre do GitHub e constrói o site com Hugo, tendo a raiz do documento do servidor web como alvo para o site renderizado. Visualizamos este site de encenação e confirmamos que o conteúdo aparece como esperado.
     
     O servidor de encenação não fazia inicialmente parte do nosso fluxo de trabalho; ele foi construído após um incidente que quebrou temporariamente nosso CSS/styling durante uma atualização do site de produção. Em resumo, a Netlify tinha feito uma pré-visualização correta do novo lançamento do site, mas não conseguiu identificar um problema de estilo. Isto porque utilizou o nosso 'desenvolvimento' construir gasoduto, em vez do nosso 'produção' construir gasoduto (que diminui o nosso CSS e outros ativos). O novo servidor de encenação está configurado com a mesma configuração do nosso servidor de produção, por isso também utiliza o gasoduto de construção de produção, e vai identificar erros como este.
     
   • Para atualizar o site de produção, nós criamos uma nova tag de lançamento no GitHub. Isso aciona outra notificação do gancho da web que é enviada para o servidor web de produção. Este servidor executa um script semelhante ao servidor de encenação, mas em vez disso puxa para baixo o conteúdo da nova tag de lançamento.
   • Ter a nossa função de publicação acontece automaticamente minimiza qualquer erro humano que possa ocorrer se formos executar manualmente este processo. Os servidores de encenação e produção estão ambos sob gestão de configuração através de fórmulas de Sal, o que também minimiza os erros humanos quando eles precisam de qualquer manutenção ou atualização de software. O sal também é utilizado por outros projetos de infraestrutura na Linode, de modo que nossos servidores web docs podem ser gerenciados ao lado de outras partes da frota.

A adoção desta metodologia tem nos ajudado muito a agilizar nosso fluxo de trabalho, mas estamos sempre trabalhando para melhorar. Se você tiver alguma sugestão de atualização que possamos fazer, nos avise! Estou no Write the Docs Slack como nmelehan, assim como vários outros membros da equipe. Se você gostaria de ler mais sobre os documentos como código, eu recomendaria o guia de Eric Holscher no site Write the Docs.