Docs-as-Code: Um guia básico para iniciantes
Nesta publicação, mergulhamos profundamente no mundo do Docs-as-Code, explorando desde os desafios enfrentados na documentação tradicional até as soluções inovadoras que essa metodologia oferece. Abordaremos os quatro pilares fundamentais do Docs-as-Code, que servem como a base para transformar a maneira como criamos, gerenciamos e mantemos a documentação técnica em paralelo com o desenvolvimento de software.
Além disso, destacaremos as ferramentas indispensáveis que facilitam a implementação eficiente do Docs-as-Code, oferecendo um panorama das melhores práticas para escolher e utilizar essas ferramentas no seu fluxo de trabalho.
Venha nesta aventura para descobrir como o Docs-as-Code está transformando as práticas de documentação no desenvolvimento de software, favorecendo mais eficiência, cooperação e harmonia entre código e documentação.
Problema
No mundo acelerado do desenvolvimento de software, a maneira como gerenciamos e mantemos a documentação é tão crucial quanto o código em si. No entanto, muitas vezes a documentação era relegada a um papel secundário, sem uma integração adequada com o código.
Isso resultava em uma documentação fragmentada e inconsistente, que podia ser encontrada em diferentes plataformas, como wikis internas ou sistemas de gerenciamento de conteúdo variados. Essa dispersão não apenas complicava a gestão da documentação, mas também criava um terreno fértil para inconsistências e informações desatualizadas.
Com as atualizações do software ocorrendo em um ritmo acelerado, a documentação associada lutava para acompanhar, muitas vezes resultando em um descompasso entre o que estava documentado e o estado real do software.
Segundo Esli Silva (2022), em alguma parte do trabalho, haverá uma tarefa de documentação e neste antigo modelo de desenvolvimento de software sequencial, o processo é visto como um fluir constante para frente… daquele ponto da documentação em diante, tudo já será inútil. Pois a documentação foi escrita e entregue em um ponto na linha do tempo.
Solução
Diante desses desafios, surgiu uma filosofia inovadora que oferecia uma solução permanente. Essa nova abordagem, chamada de documentação como código (Docs-as-Code), sugere tratar a documentação com o mesmo rigor e cuidado aplicados ao código de software. Essa não é apenas uma moda passageira, mas uma evolução natural das melhores práticas de engenharia de software, que considera a documentação como uma parte essencial do ecossistema de desenvolvimento.
Ao adotar a metodologia Docs-as-Code, as equipes de desenvolvimento integram a criação e manutenção da documentação diretamente em seus fluxos de trabalho de desenvolvimento. Isso significa utilizar ferramentas de controle de versão, automação de build e revisão por pares não apenas para o código, mas também para a documentação.
A imagem acima ilustra o que foi dito anteriormente. Nela, podemos ver um pull request com as propostas de alterações na pasta src. Todas essas alterações já têm suas documentações atualizadas, pois o código e a documentação são escritos e discutidos juntos.
Se observarmos a imagem, veremos que há uma pasta chamada docs, que contém todas as mudanças para atualizar a documentação conforme as alterações feitas no código.
Por isso, a utilização desse paradigma não apenas facilita a sincronização entre documentação e código, mas também melhora significativamente a qualidade, a acessibilidade e a manutenibilidade da documentação.
Os quatro pilares fundamentais do Docs-as-Code
No coração da metodologia Docs-as-Code, jazem quatro pilares fundamentais que sustentam sua eficácia e eficiência. Esses pilares não apenas facilitam a integração da documentação no ciclo de vida do desenvolvimento de software, mas também garantem que a documentação permaneça relevante, precisa e acessível. Vamos ver como cada pilar contribui para o sucesso da documentação.
1. Versionamento
Assim como o código, a documentação deve ser versionada, permitindo que mudanças sejam rastreadas, revisadas e revertidas se necessário. Isso facilita a colaboração entre membros da equipe e garante que a documentação evolua de forma sincronizada com o código. Ferramentas de controle de versão, como Git, são fundamentais para implementar esse pilar efetivamente.
2. Automatização
A automatização desempenha um papel crucial em manter a documentação atualizada com o mínimo esforço manual possível. Isso inclui desde a geração automática de documentação a partir do código até a integração contínua (CI) para testar e publicar documentação. A automatização ajuda a reduzir os erros humanos e assegura que a documentação reflita o estado atual do software.
3. Revisão Colaborativa
Assim como o código, a documentação se beneficia enormemente da revisão por pares. Este processo não apenas melhora a qualidade e a precisão da documentação, mas também fomenta um entendimento compartilhado entre os membros da equipe. Um exemplo é a utilização da ferramenta do GitLab que facilitam essa colaboração em um Merge Request.
4. Formatos e Ferramentas Acessíveis
Utilizar formatos de arquivo abertos e ferramentas acessíveis para escrever e manter a documentação garante que todos possam contribuir facilmente, independentemente de seu papel no projeto. Markdown é um exemplo de um formato amplamente adotado devido à sua simplicidade e compatibilidade com ferramentas de versionamento.
Ferramentas indispensáveis para a eficiência do Docs-as-Code
No universo do Docs-as-Code, diversas ferramentas têm um papel fundamental para facilitar e otimizar as práticas relacionadas a essa metodologia. Essas ferramentas não só permitem a automação e o gerenciamento eficiente da documentação, como também incentivam uma cultura de colaboração e aprimoramento contínuo. A seguir, apresentamos algumas das ferramentas mais utilizadas:
Sistemas de controle de versão (Git)
O uso de sistemas de controle de versão, como Git, é fundamental para o versionamento da documentação. Essas ferramentas permitem que as equipes rastreiem alterações, colaborem em revisões e mantenham um histórico completo das mudanças na documentação, assim como fazem com o código.
Plataformas de hospedagem (GitHub, GitLab, Bitbucket)
Plataformas como GitHub, GitLab e Bitbucket vão além do simples controle de versão, oferecendo recursos para hospedagem de repositórios, revisão de código, integração contínua (CI/CD) e gerenciamento de projetos. Elas facilitam a revisão colaborativa da documentação por meio de pull requests e issues, integrando a documentação de forma mais estreita com o fluxo de trabalho de desenvolvimento.
Ferramentas de automação e integração contínua (Jenkins, GitHub Actions, GitLab)
Ferramentas de automação e integração contínua como Jenkins, GitHub Actions e GitLab podem ser configuradas para compilar, testar e implantar documentação automaticamente. Isso assegura que a documentação seja consistentemente atualizada a cada nova alteração no código, reduzindo o risco de desatualização.
Sistemas de geração de sites estáticos (Jekyll, Hugo, Docusaurus)
Sistemas de geração de sites estáticos como Jekyll, Hugo e Docusaurus são excelentes para criar sites de documentação a partir de arquivos de texto simples, como Markdown. Eles são especialmente úteis para gerar documentação que é fácil de navegar, pesquisar e hospedar, com o benefício adicional de alta performance e segurança.
Ferramentas de documentação API (Swagger, Redoc)
Para projetos de software com APIs, ferramentas como Swagger (OpenAPI) e Redoc são essenciais para gerar documentação interativa e explorável para APIs. Elas permitem que desenvolvedores e usuários finais entendam e testem a API de forma intuitiva, garantindo que a documentação da API seja clara e útil.
Exemplo de utilização do Docs-as-Code
O GitLab é um excelente exemplo de empresa que utiliza a filosofia Docs-as-Code com sucesso. Toda a documentação da plataforma, como tutoriais, guias de referência e APIs, é gerenciada usando um fluxo de trabalho de documentação como código. Essa metodologia permite que a equipe do GitLab, produza uma grande quantidade de conteúdo de alta qualidade com eficiência.
Na Figura 2, podemos observar a pasta doc que é dedicada à documentação no repositório do GitLab. Sempre que há uma alteração nesta pasta, diversas etapas de validações são realizadas automaticamente por meio das ferramentas de CI/CD do GitLab.
Ferramentas:
- Nanoc: Uma ferramenta para geração de sites estáticos a partir de arquivos Markdown. O Nanoc permite que a documentação seja facilmente publicada e atualizada.
- Vale.sh: Uma ferramenta para verificação de ortografia e gramática em português. O Vale.sh garante que a documentação esteja livre de erros gramaticais e ortográficos.
- Markdownlint: Uma ferramenta para validação da estrutura de arquivos Markdown. O Markdownlint garante que a documentação esteja formatada conforme as melhores práticas.
Além do repositório principal mencionado anteriormente, o GitLab utiliza outro repositório GitLab Docs dedicado à estrutura da página da documentação.
Neste repositório, são feitas configurações como a definição de menus, cores, códigos CSS e JavaScript. O repositório também utiliza ferramentas de automação por meio do pipeline de CI/CD. Através do pipeline, o conteúdo da documentação é baixado do repositório principal, convertido de Markdown para HTML e compilado em um site estático. O código HTML final é então hospedado nas páginas do GitLab Pages, no site docs.gitlab.com.
Ter a documentação gerada por um pipeline significa que podemos atualizá-la a qualquer momento, garantindo que ela esteja sempre alinhada com o código-fonte. Isso porque qualquer alteração na estrutura de código principal será documentada na pasta doc. Assim, por vários motivos, é essencial usar o fluxo de trabalho do docs-as-code. Com ele, você terá muitas vantagens, tais como:
- Melhoria na manutenção da documentação: A documentação é gerada automaticamente a partir do código, reduzindo o tempo e o esforço manual na sua criação e atualização.
- Colaboração entre equipes: O Docs-as-Code facilita a colaboração entre desenvolvedores e redatores de documentação, pois todos trabalham com a mesma fonte de verdade: o código.
- Automação do processo: O processo de criação e atualização da documentação pode ser automatizado por meio de pipelines de CI/CD, garantindo agilidade e consistência.
- Rastreabilidade de alterações: O uso do controle de versão na documentação permite rastrear alterações com histórico de versões, facilitando a identificação de quem fez o quê e quando.
Para obter mais informações sobre a documentação como código na plataforma do GitLab, recomendo a leitura da publicação a seguir:
Desafios comuns ao utilizar o Docs-as-Code e como superá-los
A adoção do Docs-as-Code representa uma mudança importante na forma como as equipes de desenvolvimento lidam com a criação, manutenção e atualização de documentos técnicos. Essa metodologia oferece muitos benefícios, como melhor colaboração, versionamento consistente e integração de ferramentas de automação, mas também envolve alguns desafios na sua implementação. Neste artigo, analisamos alguns dos problemas mais frequentes e sugerimos estratégias para resolvê-los.
Desafios em ambientes colaborativos
Desafio: A colaboração entre redatores técnicos e desenvolvedores é fundamental no Docs-as-Code. No entanto, isso pode levar a inconsistências nos estilos de escrita e dificuldades na coordenação dos esforços de documentação.
Solução: A adoção de guias de estilo é crucial para manter a uniformidade. Estes guias detalham as convenções de escrita, formatação e estruturação do conteúdo, garantindo que todos os colaboradores sigam as mesmas diretrizes. Além disso, ferramentas de revisão colaborativa, como pull requests em plataformas de versionamento de código, podem ajudar a alinhar as contribuições de todos os envolvidos com os padrões definidos.
Curva de aprendizado em ferramentas e práticas
Desafio: Aprender a utilizar as ferramentas específicas do Docs-as-Code e adaptar-se às práticas de desenvolvimento de documentação pode ser desafiador para equipes acostumadas a métodos tradicionais.
Solução: Organizar sessões de treinamento e oferecer recursos educacionais são passos fundamentais para facilitar a adaptação. Criar uma comunidade de prática dentro da organização pode ajudar na troca de conhecimentos e experiências, acelerando a curva de aprendizado.
Integração de ferramentas diversificadas
Desafio: Escolher e integrar as diversas ferramentas necessárias para suportar o fluxo de trabalho do Docs-as-Code pode ser complexo, especialmente para organizações maiores com muitas necessidades variadas.
Solução: Realizar uma análise detalhada das necessidades de documentação da equipe e selecionar ferramentas que melhor se alinhem com esses requisitos é essencial. A padronização de um conjunto de ferramentas em toda a organização pode simplificar a integração e a colaboração. Além disso, buscar ferramentas que ofereçam integrações nativas entre si pode reduzir significativamente a complexidade do processo.
Conclusão
À medida que navegamos pela evolução constante do desenvolvimento de software, a abordagem Docs-as-Code emerge como um farol de inovação, transformando radicalmente a maneira como criamos, gerenciamos e compartilhamos documentação técnica. Incorporando práticas de desenvolvimento ágeis e aproveitando ferramentas de controle de versão e automação, Docs-as-Code não apenas facilita a colaboração entre redatores técnicos e desenvolvedores, mas também assegura que a documentação permaneça atualizada, acessível e alinhada com o software que descreve.
Enfrentamos, é claro, desafios na adoção dessa metodologia, desde a adaptação a novas ferramentas até a manutenção de uma voz coesa em um ambiente colaborativo. No entanto, as soluções para esses obstáculos, como a implementação de guias de estilo, o uso eficaz do controle de versão e a promoção de sessões de treinamento, revelam que os benefícios superam em muito as dificuldades.
Além disso, a seleção cuidadosa de ferramentas que complementam e se integram ao fluxo de trabalho do Docs-as-Code pode simplificar significativamente o processo, permitindo que as equipes concentrem mais tempo e recursos no desenvolvimento de produtos de alta qualidade, em vez de na luta contra a desatualização da documentação.
Em última análise, a jornada para implementar Docs-as-Code é tanto sobre a transformação cultural quanto sobre a mudança técnica. Promove uma mentalidade onde a documentação é vista como parte integrante do produto de software, não como uma tarefa secundária.
Ao abraçar completamente os princípios do Docs-as-Code, as organizações podem desbloquear um nível de eficiência e sinergia entre desenvolvimento e documentação, pavimentando o caminho para um futuro onde software e sua documentação evoluem em perfeita harmonia.
Referências
Esta publicação foi embasada em algumas referências bibliográficas, que foram fundamentais para a construção do conteúdo apresentado. Recomendamos a leitura dessas referências, a fim de obter uma compreensão mais aprofundada do tema abordado neste artigo. Ao consultar essas fontes, você terá acesso a informações adicionais e poderá explorar aspectos específicos do Docs-as-code.
- GitLab. “Five Fast Facts About Docs as Code at GitLab.” GitLab Blog, 12 Oct. 2022, https://about.gitlab.com/blog/2022/10/12/five-fast-facts-about-docs-as-code-at-gitlab/.
- Anne, Ezinne. “Docs as Code: A Brief Introduction.” Medium, https://medium.com/@ezinneanne/docs-as-code-a-brief-introduction-4fe15b7f0b4c.
- Olatunji, Mayowa. “Introduction to Docs as Code: Common Challenges and Best Practices.” Medium, https://medium.com/@olatunjimayowa0396/introduction-to-docs-as-code-common-challenges-and-best-practices-5689f3eed40f.
- Technical Writer HQ. “Technical Writer Style Guide.” Technical Writer HQ, https://technicalwriterhq.com/writing/technical-writing/technical-writer-style-guide/.
- Ryan, Michael James. “Docs as Code and DevOps Success.” Medium, https://medium.com/@michaeljamesryan/docs-as-code-and-devops-success-871bb174631d.
- “Documentation as a Code.” Medium, https://8grams.medium.com/documentation-as-a-code-4e821540edad.
- Pugh, Tom. “Trends to Follow (or Forget): Docs as Code.” I’d Rather Be Writing, https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html#what-is-docs-as-code.
- Esli, João. “Docs as Code: Documentação Como Código.” Esli Blog, https://esli.blog.br/docs-as-code-documentacao-como-codigo.
- Esli, João. “Doc as a Code: DocOps & SRE.” Esli Blog, https://esli.blog.br/doc-as-a-code-docops-sre#heading-doc-as-a-code.
