Docs como Código em Linode

Olá! Meu nome é Nathan, e sou membro da equipe de redação técnica 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 incentivar a colaboração no processo de redação, 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 documentação são as mesmas que as ferramentas utilizadas para escrever software. Isto inclui:

• Usando software de controle de versão
• Escrever arquivos de documentação em texto simples
• Execução de testes automatizados
• Praticando 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 infra-estrutura da nuvem que hospeda nosso website de documentos.

Por que Docs como Código?

Seguir estas práticas oferece uma gama 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 de nosso processo. Por exemplo: a equipe de front-end pode ajudar a atualizar a temática/apresentação para o website dos documentos usando as ferramentas com as quais já trabalham, e um membro da equipe de engenharia pode escrever novos testes automatizados para a biblioteca dos documentos.
  
• 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 nos idiomas 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, gostaria de oferecer um esboço detalhado de nosso processo:

1. Autoria: Nossos redatores técnicos são autores de novos guias em Markdown. Markdown é usado para representar um texto rico em um arquivo de texto simples, e pode ser compilado em HTML por uma série de ferramentas. Markdown tem adoção quase universal no desenvolvimento de software; por exemplo, os arquivos GitHub README são escritos em Markdown. Escrever em 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 com nossa biblioteca.
   
2. Antevisões locais do site: Os arquivos Markdown em nossa biblioteca são compilados em sua representação HTML final com um gerador de sítio 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 sites estáticos torna um site estático ao combinar seus arquivos de conteúdo (por exemplo, Markdown) com um tema que você especifica.
   
   O website de documentos da Linode utiliza Hugoque é um dos os geradores de sites estáticos mais populares:
   
   • Hugo oferece métodos de instalação bem documentados em muitos sistemas operacionais, portanto, não há problemas quando se embarca em 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 será carregado ao vivo sempre que o autor salvar seu arquivo.
     
   • Hugo é extremamente rápido, o que é um fator significativo para uma biblioteca de nosso tamanho - meu Macbook Pro é capaz de compilar todas as 1400 guias em aproximadamente 3 segundos, e a função de recarga ao vivo é quase instantânea. 
     
   • Os atalhos de Hugo também nos ajudam a melhorar nossos guias com características que Markdown não oferece, incluindo notas destacadas e trechos de código numerados por linha.
     
     
3. Colaboração: A biblioteca de documentos é armazenada em um repositório público Git hospedado no GitHub, e cada autor mantém um garfo deste repositório. Quando um autor termina de redigir um guia, ele submete suas alterações, empurra as alterações até o garfo 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 da solicitação 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 sua utilização 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 Netlify para gerar previsões automáticas, acessíveis ao público, para cada solicitação de puxar. Muitas vezes precisamos pedir feedback aos Linodians em diferentes departamentos, e eles podem visualizar esses links compartilháveis 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, o que é bem-vindo.
   
4. Testes: Sempre que um pedido de puxar é apresentado ou atualizado, uma série de testes são executados sobre o conteúdo do RP. Estes testes são executados com Travis CIque é um serviço de integração contínua que também oferece a integração GitHub. Se qualquer um destes testes falhar, então o pedido de puxar é temporariamente bloqueado para não ser fundido:
   
   • O conteúdo do guia é verificado quanto à ortografia e ao estilo (por exemplo, capitalização adequada dos termos técnicos). Utilizamos a Vale para realizar estas 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.000 erros ortográficos em nossa biblioteca. Embora um pouco embaraçoso, conhecer este número e depois poder atuar sobre ele nos deu um grande impulso na confiança em nosso conteúdo e em nosso novo sistema de publicação.
     
   • Verificamos a possibilidade de quebra de links entre guias usando Scrapy, uma estrutura de código aberto Python que raspa conteúdo de websites. Este teste foi escrito em colaboração com um membro da equipe de engenharia da Linode. Ao implementar o Scrapy pela primeira vez, encontramos, de forma semelhante, uma série de links quebrados que pudemos corrigir.
     
   • Outro Python script verifica se os metadados da matéria frontal para guias são válidos e livres de erros de sintaxe. Uma seção de front-matter quebrada pode causar problemas ao construir o site, portanto, ter isso validado significa que podemos ter certeza de que o site renderá ao atualizar os servidores web de produção.
     
5. Publicação e Hospedagem: A atualização do website dos documentos é 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 do gancho da web é enviada para um servidor web de encenação, que é um Linode. Este servidor web de encenação então puxa a filial principal do GitHub e constrói o site com Hugo, tendo a raiz do documento do servidor web como alvo para o site renderizado. Vemos este site de encenação e confirmamos que o conteúdo aparece como esperado.
     
     O servidor de encenação não fazia inicialmente parte de 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 corretamente uma previsão do lançamento do novo site, mas não conseguiu detectar um problema de estilo. Isto se deveu ao fato de ter utilizado nosso pipeline de "desenvolvimento", ao invés de nosso pipeline de "produção" (que minifica nosso CSS e outros ativos). O novo servidor de encenação é configurado com a mesma configuração de nosso servidor de produção, portanto, ele também usa o gasoduto de construção de produção, e ele irá detectar erros como este.
     
   • Para atualizar o site de produção, criamos uma nova etiqueta de lançamento no GitHub. Isto aciona outra notificação de lançamento que é enviada para o servidor web de produção. Este servidor executa um script semelhante ao servidor de encenação, mas, em vez disso, retira o conteúdo da nova tag de lançamento.
   • Ter nossa função de publicação acontece automaticamente minimiza qualquer erro humano que poderia ocorrer se realizássemos este processo manualmente. Os servidores de encenação e produção estão ambos sob gerenciamento de configuração através de Salt O site Salt também é utilizado por outros projetos de infra-estrutura na Linode, de modo que nossos servidores web docs podem ser gerenciados ao lado de outras partes da frota.

A adoção desta metodologia nos ajudou muito a racionalizar nosso fluxo de trabalho, mas estamos sempre trabalhando para iterá-lo e melhorá-lo. 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.