À medida que uma empresa cresce, é comum que a equipe de Engenharia de Software também cresça. E conforme a equipe cresce, a documentação também cresce (ou espero que sim). Diagramas, RFC’s, tutoriais de configurações, decisões de negócios e todo tipo de registro começam a se tornar mais importantes para cada engenheiro que entra ou sai da empresa.

Neste ponto (e preferencialmente, no início da empresa) é importante definir uma Single Source of Truth, principalmente para a documentação. Mas antes de mais nada, o que é uma Single Source of Truth?

Single Source of Truth⌗

Uma Single Source of Truth (SSOT) é uma técnica sobre coletar dados de vários sistemas organizacionais e colocá-los em um local centralizado. Uma SSOT é um estado dos dados de uma empresa em que tudo pode ser localizado por meio de um único ponto de referência, em vez de um sistema, ferramenta ou estratégia.

E por que isso é importante?⌗

Armazenar o conhecimento de sua equipe em um local único, fácil de encontrar e contribuir, ajuda muito a não perder informações e decisões durante o crescimento das equipes. Além disso, pode facilitar a etapa de onboarding, causando menos necessidade de reuniões síncronas para transferência de conhecimento. Além disso, não ter um local único podem acarretar em termos dados legados que não seguem mais a realidade.

Imagine entrar em uma nova empresa e ter que ir pessoa por pessoa, equipe por equipe, perguntando onde está a documentação ou porque algo foi feito de alguma forma. Imagine ter que entrar no Jira, Miro, GitHub, Excalidraw, Trello, Google Drive (e mais 27 outras ferramentas) apenas para verificar algo que poderia ser um arquivo Markdown em algum repositório geral da engenharia no GitHub.

Quais opções eu tenho?⌗

Olhando para o mercado, temos inúmeras opções para documentar e armazenar dados. É importante colocar na mesa o quão fácil é usar e contribuir, e o quanto seus colegas de trabalho estão confortáveis com a ferramenta em questão. Pessoalmente, gosto muito de usar o GitHub para equipes de engenharia. E quando digo usar, quero dizer usar tudo que a ferramenta oferece, não só a parte de versionamento, mas também o Project, Wiki, Actions, etc.

Neste post, vamos nos concentrar no controle de versão do código e no recurso Projects do GitHub. Com o versionamento de código, você pode armazenar sua documentação em alguns arquivos Markdown (lembre-se de usar um repo comum para isso), versionando as informações e garantindo a integridade dos documentos. Além disso, com uma estrutura Markdown, fica fácil migrar para alguma outra ferramenta posteriormente, se você quiser. É válido dizer que você também pode usar o GitHub Wiki para armazenar esse tipo de dados.

Quando pensamos em diagramas, existem algumas ferramentas que podem ajudar no versionamento deles, permitindo que os diagramas funcionem na ideia de Diagram as Code. Mermaid e Diagrams são algumas das opções.

Já o GitHub Projects é muito útil como uma ferramenta para organizar sua estrutura de fluxo de trabalho (Scrum, Kanban, Scrumban, etc). Você pode criar issues que se transformam em cards e vincular Pull Requests a elas. As issues são uma ótima maneira de registrar discussões técnicas. Além disso, você pode automatizar o status dos cards no projeto com pouco esforço. Há algum tempo atrás, comecei a trabalhar em um projeto que usava o GitHub Projects, mas depois migramos para outra ferramenta de board devido à falta de recursos fáceis para coleta de métricas. Hoje em dia, é um recurso nativo do GitHub.

Pensando nisso, o GitHub se apresenta como uma ferramenta bastante completa para diversos aspectos dos desafios do dia-a-dia da engenharia.

TL;DR (em resumo)⌗

Concentre-se em definir um único local para guardar toda a documentação da sua empresa. Comece com sua equipe de engenharia, mas leve a ideia para outros departamentos da sua empresa. Não se preocupe em pensar demais sobre como começar ou qual ferramenta usar. Atlassian, GitHub, Azure, todas oferecem ferramentas e recursos de boa qualidade para te ajudar nessa missão. Dê o ponta pé inicial e entenda os prós e contras durante o processo. Você pode mudar para outro lugar rapidamente se estruturar um bom começo, usando recursos que permitem essa fácil migração, como o Markdown. Quanto mais cedo você começar, melhor.