33 Decisoes Design Registradas

Introdução

“Por que fizemos isso dessa forma mesmo?” – uma pergunta comum em projetos de longa duração, incluindo Design Systems. Com o tempo, o raciocínio por trás de decisões importantes pode se perder, levando a retrabalho, inconsistências ou à repetição de erros passados. Para combater essa amnésia coletiva, a prática de manter Decisões de Design Registradas é fundamental. Inspirada nos Architecture Decision Records (ADRs) do mundo da arquitetura de software, essa prática envolve documentar de forma estruturada as escolhas significativas, seu contexto e suas consequências. Manter um log dessas decisões transforma o conhecimento tácito em explícito, criando uma base sólida para a evolução sustentável do Design System.

O que são Decisões de Design Registradas (DDRs / ADRs)?

Decisões de Design Registradas (que podemos chamar de DDRs ou simplesmente adaptar o termo ADR para o contexto do DS) são artefatos de documentação curtos e focados, cada um descrevendo uma única decisão arquitetural ou de design significativa para o sistema.

Um formato comum para um ADR/DDR inclui seções como:

1. Título: Um nome curto e descritivo para a decisão (ex: “Adotar Styled Components para Estilização”, “Usar Nomenclatura BEM para CSS Fallback”).
2. Status: O estado atual da decisão (ex: Proposta, Aceita, Rejeitada, Substituída).
3. Contexto: A situação, problema ou requisito que levou à necessidade de tomar essa decisão. Quais forças estavam em jogo?
4. Decisão: A declaração clara da escolha que foi feita.
5. Opções Consideradas: Uma breve descrição das alternativas que foram avaliadas (incluindo a opção escolhida).
6. Justificativa / Consequências: O raciocínio por trás da escolha. Por que essa opção foi selecionada em detrimento das outras? Quais são os resultados esperados (positivos e negativos)? Quais trade-offs foram aceitos?
7. Data: Quando a decisão foi tomada.

Esses registros são geralmente mantidos como arquivos Markdown simples em um diretório específico dentro do repositório do Design System, facilitando o versionamento e a revisão.

Por que é importante?

Manter um log de decisões de design traz múltiplos benefícios:

1. Preservação do Conhecimento: Evita a perda do contexto e do raciocínio por trás das escolhas à medida que a equipe muda ou o tempo passa.
2. Onboarding Acelerado: Novos membros podem rapidamente entender o histórico e as justificativas das decisões chave do sistema.
3. Evitar Repetição de Debates: Se uma questão já foi decidida e registrada, pode-se referenciar o DDR/ADR em vez de reabrir a discussão do zero.
4. Base para Evolução: Informa decisões futuras, permitindo construir sobre o conhecimento passado ou revisitar decisões anteriores com base em novas informações.
5. Transparência e Alinhamento: Torna o processo de tomada de decisão mais transparente para a equipe e stakeholders.
6. Melhor Comunicação: Fornece uma forma estruturada de comunicar decisões complexas.
7. Responsabilidade: Documenta quem tomou a decisão e quando (embora o foco seja no raciocínio).
8. Auditoria e Conformidade: Pode ser útil para rastrear decisões relacionadas a requisitos específicos (ex: acessibilidade, segurança).

Como o Spotify Engineering discute, ADRs ajudam a entender não apenas o quê foi decidido, mas por quê.

Como aplicar na prática?

Implementar o registro de decisões de design envolve estabelecer um processo:

1. Definir o Gatilho: Determinar quais tipos de decisões justificam um registro. Geralmente são aquelas que têm um impacto significativo na arquitetura, tecnologia, padrões principais ou processos do DS, ou que foram resultado de um debate considerável.
2. Escolher um Formato/Template: Adotar um template simples e consistente para os registros (ex: baseado nos templates de Michael Nygard ou Joel Parker Henderson para ADRs). Manter a simplicidade é chave.
3. Selecionar o Local de Armazenamento: Geralmente, um diretório (docs/decisions, adr, etc.) dentro do repositório Git do Design System é o ideal, permitindo versionamento junto com o código e a documentação.
4. Integrar ao Fluxo de Trabalho: Incorporar a criação ou atualização de DDRs/ADRs como parte do processo de design e desenvolvimento. Por exemplo, uma nova proposta de componente pode incluir um DDR/ADR inicial, que é finalizado quando a proposta é aceita.
5. Manter Conciso: Focar no essencial. Um bom registro tem geralmente 1-2 páginas.
6. Numerar Sequencialmente: Atribuir um número sequencial a cada registro para fácil referência (ex: 001-uso-de-tokens-semanticos.md).
7. Criar um Log ou Índice (Opcional): Um arquivo README.md no diretório de decisões pode listar todos os registros com seus títulos e status para fácil navegação (como sugerido pela Microsoft).
8. Revisitar e Atualizar Status: Quando uma decisão antiga é substituída por uma nova, marcar o registro antigo como “Substituído” e referenciar o novo registro.
9. Promover a Cultura: Incentivar a equipe a ver o registro de decisões como uma prática valiosa, não como burocracia.

Ferramentas ou frameworks relacionados

• Markdown: Formato de arquivo mais comum para escrever os registros.
• Git (GitHub, GitLab, Bitbucket): Essencial para versionar os registros junto com o código e a documentação.
• Templates de ADR: Existem vários templates disponíveis online (Michael Nygard, Joel Parker Henderson, etc.) que podem ser adaptados.
• Ferramentas de Linha de Comando (CLI) para ADRs: Existem algumas ferramentas como adr-tools que ajudam a criar e gerenciar arquivos ADR a partir do terminal.
• Plataformas de Documentação (Confluence, Notion): Podem ser usadas, mas perdem o benefício do versionamento integrado ao código que o Git oferece. Algumas equipes mantêm um log resumido nessas ferramentas com links para os arquivos Markdown no repositório.
• Diagramas de Arquitetura (Ex: C4 Model, UML): Podem complementar os registros de decisão, visualizando o impacto da decisão na arquitetura.

Erros comuns

• Não Registrar Nada: Confiar apenas na memória da equipe.
• Registrar Decisões Triviais: Criar registros para cada pequena escolha, tornando o log barulhento e difícil de navegar.
• Registros Muito Longos ou Detalhados: Perder o foco e a concisão, tornando os registros difíceis de ler.
• Falta de Contexto ou Justificativa: Registrar a decisão, mas não explicar adequadamente por quê ela foi tomada.
• Armazenamento Inadequado: Guardar os registros em locais dispersos ou que não são facilmente acessíveis ou versionáveis.
• Não Atualizar Status: Deixar registros obsoletos marcados como “Aceitos”, causando confusão.
• Processo Burocrático: Tornar a criação de registros tão onerosa que a equipe evita fazê-lo.
• Falta de Adoção pela Equipe: A prática não é abraçada pela equipe e acaba sendo abandonada.

Conclusão

Registrar as decisões de design significativas é uma prática de higiene essencial para a longevidade e a saúde de um Design System. Ao adotar um formato simples e consistente (como os ADRs adaptados) e integrar o processo ao fluxo de trabalho, criamos um registro valioso que preserva o conhecimento, facilita o alinhamento e informa a evolução futura do sistema. Embora exija disciplina, o esforço de documentar o “porquê” por trás das escolhas economiza tempo e evita dores de cabeça a longo prazo, tornando o Design System mais robusto, transparente e sustentável.

Referências

1. Henderson, Joel Parker. Architecture Decision Record (ADR) Examples. GitHub Repository. Recuperado de https://github.com/joelparkerhenderson/architecture-decision-record
2. ADR GitHub Organization. Architectural Decision Records. Recuperado de https://adr.github.io/
3. Spotify Engineering. (2020). When Should I Write an Architecture Decision Record. Recuperado de https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record
4. Microsoft Code With Engineering Playbook. Design Decision Log. Recuperado de https://microsoft.github.io/code-with-engineering-playbook/design/design-reviews/decision-log/
5. AWS Prescriptive Guidance. ADR process. Recuperado de https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
6. Google Cloud Architecture Center. Architecture decision records overview. Recuperado de https://cloud.google.com/architecture/architecture-decision-records