Documentação como Código

Documentação como Código (ou Documentation‑as‑Code) é uma abordagem que trata a documentação de um projeto da mesma forma que se trata o código‑fonte. Em vez de criar documentos estáticos em ferramentas separadas (como editores de texto ou wikis), a documentação é escrita em arquivos versionados, normalmente em formatos legíveis por humanos e processáveis por máquinas (Markdown, AsciiDoc, etc.) e armazenada no mesmo repositório que o código.

Principais características

Benefícios

1. Consistência – A documentação evolui junto com o código; mudanças de API ou comportamento são refletidas imediatamente.
2. Qualidade – Revisões de código aplicam padrões de escrita, ortografia e clareza, assim como revisões de implementação.
3. Transparência – Histórico completo das alterações facilita auditorias e entendimento de decisões passadas.
4. Escalabilidade – Automatizações (geração de diagramas, tabelas a partir de dados reais) mantêm a documentação atualizada sem esforço manual.
5. Unificação de processos – Equipes não precisam gerenciar duas pilhas de ferramentas diferentes (um para código, outro para docs).

Ferramentas populares

• Hugo & Docsy¹ - Geração estárica de sites que viabiliza documentação UML, OpenAPI e outros artefatos.
• MkDocs (com tema Material) – Converte Markdown em sites estáticos; integra bem com GitHub Actions.
• Sphinx – Usa reStructuredText (ou MyST Markdown) e suporta extensões para gerar documentação de APIs Python, C++, etc.
• Docusaurus – Framework React para sites de documentação; aceita MDX (Markdown + JSX).
• Read the Docs – Serviço que hospeda builds automáticos de Sphinx/MkDocs a partir de repositórios.
• GitBook, Docsify, Hugo – Outras opções para geração estática de sites.

Hugo & Docsy

“Docsy é um tema Hugo pré-configurado que fornece os principais recursos e comportamentos necessários para criar um site de documentação técnica.”

Acesse o link a seguir para observar um demonstração mais completa de Documentação como Código: https://adrianovieira.gitlab.io/plantuml-demo/

Fluxo típico de trabalho

1. Escrita – O autor cria/edita arquivos .md (ou .rst) no repositório.
2. Lint/Format – Um linter (ex.: markdownlint, vale) verifica estilo e ortografia.
3. Pull Request – A mudança é submetida a revisão; revisores verificam clareza e correção.
4. CI Build – O pipeline roda testes de build (ex.: mkdocs build). Se falhar, o PR não pode ser mesclado.
5. Deploy – Após merge, o pipeline publica a nova versão da documentação (GitHub Pages, Netlify, etc.).

Quando adotar?

• Projetos com evolução rápida ou APIs públicas que exigem documentação sincronizada.
• Times que já utilizam CI/CD e desejam centralizar todo o fluxo de entrega.
• Organizações que valorizam transparência e auditabilidade das mudanças.

Em resumo, documentação como código traz a disciplina de engenharia de software para a criação e manutenção de documentos, garantindo que eles permaneçam precisos, revisáveis e facilmente distribuídos à medida que o projeto cresce.

Artefatos de Software

Um artefato é um dos muitos tipos de subprodutos tangíveis produzidos durante o desenvolvimento de software.

Alguns artefatos (por exemplo: casos de uso, diagramas de classes, requisitos e documentos de design) ajudam a descrever a função, a arquitetura e o design do software. Outros artefatos estão relacionados ao próprio processo de desenvolvimento — como planos de projeto, casos de negócios, avaliações de risco, e diagramas de software.

E é aqui que entra o PlantUML…

PlantUML

“PlantUML é usado para desenhar diagramas UML, usando uma descrição de texto simples e legível. Tenha cuidado, pois isso não impede que você desenhe diagramas inconsistentes (como ter duas classes herdando uma da outra, por exemplo). Portanto, é mais uma ferramenta de desenho do que de modelagem.” - PlantUML.org

Diagramas

C4 Model

O C4 Model é uma técnica de notação gráfica enxuta para modelar a arquitetura de sistemas de software. Ele é baseado em uma decomposição estrutural (uma estrutura de árvore hierárquica) de um sistema em contêineres e componentes e depende de técnicas de modelagem existentes, como Unified Modeling Language (UML) ou diagramas de entidade-relacionamento (ERDs) para a decomposição mais detalhada dos blocos de construção arquitetônicos.

Código fonte

@startuml
   skinparam dpi 300
   !include <C4/C4_Container>

   AddElementTag("v1.0", $borderColor="#d73027")
   AddElementTag("v1.1", $fontColor="#d73027")
   AddElementTag("backup", $fontColor="orange")

   AddRelTag("backup", $textColor="orange", $lineColor="orange", $lineStyle = DashedLine())

   Person(user, "Customer", "People that need products")
   Person(admin, "Administrator", "People that administrates the products via the new v1.1 components", $tags="v1.1")
   Container(spa, "SPA", "angular", "The main interface that the customer interacts with via v1.0", $tags="v1.0")
   Container(spaAdmin, "Admin SPA", "angular", "The administrator interface that the customer interacts with via new v1.1", $tags="v1.1")
   Container(api, "API", "java", "Handles all business logic (incl. new v1.1 extensions)", $tags="v1.0+v1.1")
   ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and invoice information")
   Container(archive, "Archive", "Audit logging", "Stores 5 years", $tags="backup")

   Rel(user, spa, "Uses", "https")
   Rel(spa, api, "Uses", "https")
   Rel_R(api, db, "Reads/Writes")
   Rel(admin, spaAdmin, "Uses", "https")
   Rel(spaAdmin, api, "Uses", "https")
   Rel_L(api, archive, "Writes", "messages", $tags="backup")

   SHOW_LEGEND()
@enduml

Diagrama

Referências