A documentação é uma parte essencial do ciclo de desenvolvimento de software. Ele explica como usar o software e pode incluir guias do usuário, referências de API, instruções de instalação e notas de versão.
Automatizar sua documentação é a tendência mais recente, pois pode ajudar a economizar tempo, reduzir erros e garantir consistência. Manter sua documentação atualizada e acessível a todas as partes interessadas facilita a colaboração e a melhoria contínua.
Documentos como código é uma abordagem para automação de documentação que trata a documentação técnica como código.
O que é Documentos como Código?
Documentos como código é uma filosofia de desenvolvimento de software que vê a documentação técnica como uma forma de código. Ele sugere que você deve tratar a documentação com o mesmo rigor e processo que o código de software.
A ideia por trás do docs as code é tratar a documentação como um artefato de primeira classe do processo de desenvolvimento, integrando-o ao ciclo de vida do software. Isso significa tratar a documentação como parte integrante da base de código. Significa aplicar a ele o mesmo controle de versão, integração contínua e processos de teste que você aplica ao próprio código.
Em um documento típico como configuração de código, você escreve a documentação em arquivos de texto simples, geralmente em uma linguagem de marcação leve como Markdown, HTML ou reStructuredText. Em seguida, você o armazena no mesmo repositório que o código-fonte. Isso facilita o gerenciamento e o rastreamento de alterações no software e na documentação. Também ajuda a garantir que a documentação esteja atualizada com a versão mais recente do código.
Por que você deve usar documentos como código
Antes dos documentos como código, a documentação era frequentemente tratada como separada do código, criada com diferentes ferramentas e processos. Essa abordagem mais flexível geralmente levava a documentação desatualizada e inconsistências com o código. Você pode aproveitar vários benefícios adotando a abordagem de documentos como código.
Colaboração aprimorada
Documentos como código permitem a colaboração entre desenvolvedores, escritores técnicos e outras partes interessadas no processo de desenvolvimento. Como o repositório de código abriga a documentação, é fácil para diferentes partes contribuir e fazer alterações. Isso ajuda a garantir que a documentação seja precisa, atualizada e abrangente.
Uma abordagem colaborativa para a documentação ajuda a garantir que ela inclua todas as informações relevantes e que reflita com precisão o sistema de software conforme interpretado por todas as partes.
Automação de Processos e Acessibilidade
Outra vantagem dos documentos como código é que eles permitem que ferramentas automatizadas gerem e publiquem documentação. Um sistema de compilação pode gerar automaticamente versões HTML ou PDF da documentação a partir de arquivos de texto simples para publicação em um site ou portal de documentação interno. Isso torna a documentação acessível a mais partes interessadas.
Ao automatizar o processo de geração e publicação de documentação, os documentos como código ajudam a reduzir o tempo e o esforço necessários para manter e publicar a documentação. Ele permite que as equipes de desenvolvimento se concentrem na melhoria do software.
Controle de versão
Armazenar a documentação no mesmo repositório de código que o software facilita o gerenciamento e o rastreamento de alterações em ambos.
Você pode usar sistemas de controle de versão como o Git para rastrear alterações na documentação e reverter para versões anteriores, se necessário. Isso ajuda a garantir que a documentação seja precisa e atualizada, e você pode rastrear e auditar as alterações.
Os documentos típicos como fluxo de trabalho de código
Os documentos típicos como fluxo de trabalho de código compreendem escrita, controle de versão, construção e hospedagem:
O processo de escrita
O processo de escrita é a primeira etapa de um fluxo de trabalho típico de documentos como código. Maioria escritores técnicos e os engenheiros de documentação usam MarkDown, AsciiDoc ou HTML simples. Eles escrevem a documentação usando ferramentas como GitBook e Redocly, que garantem um processo tranquilo.
Controle de versão para documentação
A documentação evolui à medida que o código evolui. Você precisará de um sistema de controle de versão sofisticado, como Git, Plastic SCM ou Subversion, para rastrear alterações na documentação para facilitar a colaboração e o rastreamento de versão.
O Processo de Construção da Documentação
O processo de construção envolve processar e compilar a documentação em seus formatos de entrega. Eles podem ser HTML, PDF, EPUB ou outros. O processo de documentação geralmente é facilitado usando geradores de sites estáticos como Hugo e Jekyll.
Hospedagem e distribuição de documentação
O processo de hospedagem ou distribuição geralmente é a última etapa dos documentos como um processo de codificação. Este processo garante que a documentação seja entregue ao usuário final e disponível para todas as partes interessadas. Você pode usar as páginas GitHub ou GitLab ou um portal personalizado para distribuir sua documentação na web.
Você pode automatizar a documentação Go e Java usando GoDoc e JavaDoc
A filosofia docs as code está revolucionando a escrita e o gerenciamento de documentação técnica.
Muitas linguagens de programação, incluindo Go e Java, fornecem ferramentas para automatizar a documentação usando comentários de código. Go fornece a ferramenta Godoc e Java fornece JavaDoc.
