O que é?
Em resumo, eles são documentos feitos pelo time (especialmente pelas pessoas desenvolvedoras), com o objetivo de tornar claro e compartilhável todo o processo de desenvolvimento de uma solução. Para isso, é documentado o racional da solução adotada, alternativas, objetivos, arquitetura, entre outros pontos que detalharemos a seguir.
Mas, antes de mais nada é bom lembrarmos que seu processo de criação é tão importante quanto seu resultado final (o design doc em si), pois seu ciclo de vida é propositalmente diferente do normalmente adotado em uma documentação comum
Ref. ^medium-picpay-designdocs
Template padrão
# Documento de Atividade
## Cabeçalho
<!-- Autores, revisores, datas, tags para facilitar a indexação, etc. -->
**Autores:** Nome do Autor
**Revisores:** Nome do Revisor
**Data de Criação:** YYYY-MM-DD
**Tags:** Tag1, Tag2, Tag3
## Overview
<!-- Pequena introdução sobre o que o documento trata (um desenvolvedor sem contexto deve conseguir entender). -->
Esta seção fornece uma visão geral da atividade, explicando brevemente seu propósito e escopo.
## Contexto
<!-- Explicação dos motivos para a atividade. -->
Aqui, detalhamos o contexto que levou à necessidade desta atividade, incluindo antecedentes e justificativas.
## Objetivos
<!-- Determinantes de que a atividade foi concluída com sucesso (é interessante serem objetivos e metrificáveis, quando possível). -->
Os objetivos a seguir são os critérios de sucesso para esta atividade:
- Objetivo 1: Descrição do objetivo mensurável.
- Objetivo 2: Descrição do objetivo mensurável.
## Non-goals
<!-- Pontos que estão fora do escopo do que está sendo trabalhado nessa atividade. -->
Esta seção destaca o que não está incluído no escopo desta atividade:
- Não-objetivo 1: Descrição do ponto fora do escopo.
- Não-objetivo 2: Descrição do ponto fora do escopo.
## Alternativas
<!-- As alternativas que foram consideradas para a resolução do problema, explicando seus trade-offs e motivação da escolha. -->
Aqui listamos as alternativas consideradas, juntamente com suas vantagens e desvantagens, e explicamos a razão pela escolha final:
- Alternativa 1: Descrição e trade-offs.
- Alternativa 2: Descrição e trade-offs.
## System design
<!-- Explicação técnica da solução adotada, que pode ter code snippets, diagramas, database schemas e tudo que agregará no entendimento futuro da implementação (a maior parte do conteúdo normalmente estará aqui). -->
Esta seção detalha o design do sistema adotado, incluindo diagramas, trechos de código, esquemas de banco de dados e outros detalhes técnicos relevantes.
## Cross-cutting concerns
<!-- Possíveis pontos de bloqueio, questões relacionadas à observabilidade, infra, segurança, etc. -->
Discussão sobre preocupações transversais, como possíveis bloqueios, questões de observabilidade, infraestrutura e segurança.Links sobre
- https://www.designdocs.dev/ Diversos templates e dicas sobre como estruturar design docs.
- https://medium.com/inside-picpay/uma-introdu%C3%A7%C3%A3o-aos-design-docs-8590f28f4cc1
- https://www.industrialempathy.com/posts/design-docs-at-google/