Documentos Técnicos

À medida que os projetos de software crescem em complexidade, a necessidade de documentação técnica abrangente torna-se primordial. Sem um registro claro das decisões arquiteturais, das razões de design e das mudanças implementadas, a dívida técnica acumula-se rapidamente, tornando cada vez mais difícil manter, aprimorar ou transferir a base de código de forma eficaz.

Documentos Técnicos

Request For Comments (RFCs)

É um processo usado no desenvolvimento de software para discutir e propor ideias técnicas, projetos ou mudanças em um projeto.

Os principais aspectos de um RFC são:

1. Documento de Proposta: Um RFC começa com um documento que descreve a ideia, mudança ou solução proposta. Isso inclui o contexto, a motivação, a descrição detalhada e as potenciais consequências ou compensações.

2. Revisão da Equipe: O documento RFC é compartilhado com a equipe mais ampla ou partes interessadas relevantes para revisão e feedback. Esse processo colaborativo permite a identificação de potenciais problemas, abordagens alternativas ou melhorias para a proposta.

3. Discussão e Iteração: Com base no feedback recebido, o RFC pode passar por revisões ou esclarecimentos adicionais. Esse processo iterativo continua até que seja alcançado um consenso ou uma decisão seja tomada.

4. Decisão: Após uma discussão completa e consideração dos feedbacks, é tomada uma decisão para aceitar, rejeitar ou modificar o RFC proposto.

Os RFCs promovem a transparência, a colaboração e a documentação do processo de tomada de decisão. Eles garantem que escolhas técnicas significativas sejam bem pensadas, revisadas por múltiplas perspectivas, e que sua lógica seja registrada para referência futura.

Seguindo um processo de RFC, as equipes podem tomar decisões mais bem informadas, mitigar riscos potenciais e manter um registro claro do raciocínio por trás das escolhas arquiteturais ou mudanças em um projeto.

Registro de Decisões Arquiteturais (ADR)

Um Registro de Decisões Arquiteturais é um documento que captura uma decisão arquitetural importante tomada em um projeto de software, juntamente com seu contexto, consequências e lógica. Os ADRs servem como um registro do processo de tomada de decisão e uma base de conhecimento para referência futura.

A estrutura típica de um ADR inclui:

1. Título: Um título conciso resumindo a decisão.
2. Status: O status atual da decisão (por exemplo, proposta, aceita, obsoleta).
3. Contexto: As informações de background, declaração do problema ou contexto que levou à necessidade dessa decisão.
4. Decisão: Uma descrição detalhada da decisão que foi tomada.
5. Consequências: As consequências resultantes da decisão, incluindo benefícios e possíveis desvantagens ou compensações.

Os ADRs geralmente são escritos em um formato leve, como arquivos Markdown, e armazenados no repositório do projeto. Eles são imutáveis, o que significa que se uma decisão precisar ser revisada ou substituída, um novo ADR é criado, e o antigo é marcado como obsoleto ou substituído, com uma referência para a nova decisão.

Os principais benefícios do uso de ADRs incluem:

1. Documentação: Os ADRs documentam as decisões arquiteturais, sua lógica e o processo de pensamento por trás delas, prevenindo a perda de conhecimento ao longo do tempo ou quando membros da equipe mudam.
2. Transparência: Eles promovem a transparência ao tornar as decisões arquiteturais explícitas e acessíveis a toda a equipe.
3. Preservação de contexto: Ao capturar o contexto e as consequências, os ADRs ajudam os futuros membros da equipe a entender a lógica por trás da decisão, mesmo que os tomadores de decisão originais não estejam mais disponíveis.
4. Responsabilidade: Os ADRs estabelecem responsabilidade pelas decisões arquiteturais, facilitando o rastreamento do processo de tomada de decisão e o entendimento do raciocínio por trás de escolhas específicas.

Ao manter um conjunto abrangente de ADRs, as equipes podem gerenciar e comunicar efetivamente decisões arquiteturais importantes, facilitando o compartilhamento de conhecimento, a compreensão do código e a capacidade de raciocinar sobre mudanças futuras ou esforços de refatoração.

Postmortem

Um "postmortem" é um processo de revisão e avaliação realizado após um incidente, projeto ou evento significativo. O objetivo é analisar o que aconteceu, identificar as causas, aprender com os erros e sucessos, e determinar formas de melhorar no futuro. Aqui está uma definição mais detalhada:

Um postmortem é uma análise estruturada e retrospectiva que ocorre após um incidente, como uma interrupção de serviço, um lançamento com problemas ou um projeto concluído. Envolve reunir a equipe ou as partes interessadas relevantes para revisar o que aconteceu, explorar as causas raiz, avaliar o que foi feito bem e o que poderia ter sido feito melhor.

O processo de postmortem geralmente inclui:

1. Reconstruir uma linha do tempo detalhada dos eventos.
2. Identificar os pontos de falha, erros ou problemas que ocorreram.
3. Determinar as causas fundamentais subjacentes aos problemas.
4. Analisar as respostas e ações tomadas durante o incidente.
5. Discutir o que funcionou bem e o que poderia ser melhorado.
6. Desenvolver recomendações e lições aprendidas.
7. Determinar ações corretivas e preventivas a serem implementadas.

O objetivo de um postmortem é aprender com a experiência, evitar a repetição de erros, melhorar processos, ferramentas e práticas, além de promover a responsabilidade e a transparência dentro da equipe ou organização. É uma oportunidade para refletir criticamente, sem culpar indivíduos, e identificar áreas de melhoria.

Os postmortems são amplamente utilizados em setores como tecnologia, saúde, aviação e outros campos onde a análise de falhas e a melhoria contínua são cruciais para a segurança, confiabilidade e sucesso operacional.

Ferramentas para gerenciar a Documentação Técnica

wiki.js: Um poderoso hub de documentação

wiki.js é um software wiki de código aberto e rico em recursos que se destaca nesse papel.

Com sua interface intuitiva, integração com controle de versão e robustos controles de acesso, o wiki.js capacita equipes a documentar seus projetos de forma colaborativa, desde visões gerais de arquitetura de alto nível até detalhes de implementação granulares. Seu suporte a markdown e opções ricas de formatação facilitam a criação de documentação visualmente atraente e facilmente navegável, enquanto recursos como renderização de código e diagramas permitem que as equipes incorporem conteúdo técnico de forma transparente.

Backstage: Um portal de desenvolvedores para todo o stack técnico

O Backstage adota uma abordagem mais abrangente, servindo como um portal de desenvolvedores para todo o stack técnico. Desenvolvido pela Spotify, o Backstage visa criar um hub centralizado para todas as ferramentas de software, serviços e documentação de que os desenvolvedores precisam para serem produtivos.

O Backstage se integra a vários sistemas, incluindo controle de fonte, pipelines de CI/CD, ferramentas de monitoramento e repositórios de documentação, fornecendo uma visão unificada e ponto de entrada para os desenvolvedores. Essa experiência simplificada reduz a troca de contexto e melhora a produtividade do desenvolvedor, contribuindo, em última análise, para um processo de desenvolvimento mais eficiente e colaborativo.