Como escrever bons documentos de design

• Documento de design é um relatório técnico que organiza a estratégia de implementação, as limitações e os trade-offs de um sistema
• O documento de design tem o papel de convencer o leitor de que aquele design é adequado para o contexto
• A estrutura do documento é importante, e o fluxo lógico deve fazer com que o leitor não seja surpreendido pelo conteúdo
• Por meio da edição, é necessário reduzir palavras desnecessárias e poupar os recursos de atenção do leitor
• É importante usar parágrafos curtos e apêndices, além de aprimorar a capacidade de escrita de documentos por meio da prática

---

Definição

• Um documento de design é um relatório técnico que organiza a estratégia de implementação de um sistema no contexto de trade-offs e restrições

Objetivo

• Assim como uma prova na matemática convence sobre um teorema, o objetivo do documento de design é convencer o leitor de que aquele design é o melhor
• Durante o processo de design, o próprio ato de escrever aumenta o rigor do pensamento
• Ao escrever um documento de design, é possível transformar ideias vagas em raciocínio concreto

Organização

• A estrutura de um bom documento de design é tão importante quanto a organização do código
• Assim como iniciantes escrevem código, muitas pessoas tendem a produzir "documentos de design espaguete"
• Se as frases forem apenas listadas sem uma ordem lógica, o leitor terá dificuldade para acompanhar o contexto e ficará confuso
• Um documento excelente deve ter um fluxo natural para que o leitor não seja surpreendido, e cada frase deve se conectar à anterior de forma óbvia
• O objetivo é entender o estado de pensamento do leitor e guiá-lo gradualmente para um novo estado
• É preciso resolver antecipadamente objeções previsíveis, explicando antes que o leitor formule um contra-argumento

Edição

• Depois de organizar bem o conteúdo, a etapa de remoção de palavras desnecessárias (edição) é importante
• A atenção do leitor é um recurso limitado, e informações desnecessárias devem ser removidas sem hesitação
• Em um rascunho, é possível cortar cerca de 30% das expressões sem sentido
• Ao editar documentos de outras pessoas e desenvolver uma visão crítica, também é possível refinar com mais eficiência a própria escrita
• Praticar com tweets curtos (limite de 280 caracteres) também ajuda a simplificar o pensamento e melhorar a capacidade de condensação

Experiência e prática

• Não há atalho melhor para desenvolver habilidade do que a prática repetida
• A experiência com a cultura centrada em documentos da Amazon ajudou muito a melhorar a capacidade de escrita
• Em reuniões importantes, usa-se o método de distribuir documentos de design de 1 a 6 páginas e, em seguida, todos leem em silêncio e anotam opiniões nas margens
• Receber feedback permite melhorar de forma concreta a habilidade de escrita

Dicas concretas

Uso de parágrafos curtos

• O documento de design deve criar fluxo com bullet points concisos e contínuos
• Cada bullet point (observação, ideia, problema, melhoria etc.) deve ser composto por um parágrafo curto focado em um único conceito
• Cada parágrafo deve ter clareza suficiente para poder ser resumido em uma frase, o que ajuda a economizar os recursos de memória de curto prazo do leitor

Uso de apêndices

• Cálculos complexos ou resultados de simulações devem ser organizados em detalhes em apêndices, e no corpo principal do documento devem ser mencionados apenas em forma de nota breve
• Os apêndices não são essenciais para entender as principais conclusões do texto, mas ficam disponíveis para leitores interessados consultarem

Exemplo de edição

• (Antes da edição, parágrafo prolixo):

  Cada bullet point deve ser um parágrafo separado no documento. Cada parágrafo deve poder ser resumido em uma frase. Não precisa de fato ser uma única frase, e explicações adicionais podem ser incluídas para explicar o conceito. Mas, depois de ler, o leitor deve conseguir resumi-lo em uma frase.

• (Depois da edição, parágrafo condensado):

  Cada bullet point deve ser um parágrafo que possa ser resumido em uma frase. Não precisa ser literalmente uma única frase, e explicações adicionais podem ser incluídas se necessário. Mas, depois da leitura, ele deve poder ser condensado em uma frase.

Encerramento

• O documento de design é um processo importante no qual é possível desenvolver capacidade por meio de rigor do pensamento, fluxo lógico, edição centrada no leitor e prática repetida

[GN⁺]

Comentários do Hacker News

• O comentário apresenta duas citações que chamaram especialmente a atenção no artigo. A primeira, de uma captura de tela no X, diz que "no processo de escrever, as ideias ficam 10 vezes melhores". A segunda, logo no início, diz que "a pessoa mais importante que você precisa convencer é você mesmo". É surpreendente que, mesmo após anos trabalhando no setor, ainda existam pessoas contrárias à necessidade de documentos de design. Leslie Lamport disse que "escrever é a maneira que a natureza tem de nos dizer o quão confuso é o nosso pensamento". Para quem quiser desenvolver melhor a escrita técnica, a recomendação é o texto Write Like an Amazonian(https://medium.com/@apappascs/…)
  • A recomendação de "transformar adjetivos em dados" parece ter se espalhado tanto pelo setor de tecnologia que hoje muitos currículos estão cheios de números a ponto de ficar difícil entender o que realmente significam
• Como revisor de design, há um ponto que todo autor de documento precisa internalizar. É a ideia de que "um bom documento faz o leitor entender o problema e o modelo mental, de modo que, quando a solução surgida após semanas de reflexão é finalmente apresentada, ela pareça naturalmente convincente". Minha citação favorita é "se eu tivesse mais tempo, teria escrito uma carta mais curta". Um documento de design precisa simplificar conteúdos complexos e não deve ser um lugar para despejar indiscriminadamente todos os altos e baixos e fracassos vividos pelo desenvolvedor. Esse tipo de conteúdo pode até ser útil, mas é melhor organizá-lo em um documento separado ou em apêndices. É preciso mostrar de forma simples o caminho a seguir
  • Prefiro a formulação "mais tempo, carta mais curta"
  • Sempre faço estas perguntas a mim mesmo: "isso vai gerar uma discussão inútil sobre este tema?", "vale a pena discutir isso?" Meu objetivo é permitir que novos leitores entrem na discussão sem dificuldade e evitar controvérsia em partes que não são importantes
• As reuniões na Amazon começam com o apresentador distribuindo um documento em prosa. Todos se sentam em silêncio, leem o documento e fazem anotações e perguntas nas margens com caneta vermelha. Nunca trabalhei de fato na Amazon, mas esse método parece surpreendentemente eficaz, e todas as pessoas que relatam essa experiência parecem gostar dele. Pode parecer ineficiente passar um tempo valioso de reunião apenas lendo juntos, mas, se todos lessem e se preparassem antes, seria possível ter reuniões mais curtas. A leitura simultânea em tempo real faz com que se espere pelos leitores mais lentos ou que todos passem um tempo vago por entenderem o conteúdo em níveis diferentes por falta de contexto. Quando fazia design reviews no Google, frequentemente via a maioria dos participantes entrando na discussão vendo o documento pela primeira vez e sem preparo prévio. Acho que isso acontecia porque o Google não tinha uma cultura forte de documentação, e porque líderes de equipe e gerentes implicitamente toleravam chegar despreparados. Se houvesse uma cultura bem estabelecida de leitura prévia obrigatória, o tempo de reunião poderia ser usado com muito mais eficiência
  • As pessoas dizem que ler com antecedência reduz o tempo da reunião, mas a prática da Amazon é uma resposta à realidade de que, na prática, as pessoas não leem antes. Em um artigo antigo sobre o tema, dizia-se que criar uma cultura forte de leitura prévia era praticamente impossível. Todos os participantes não conseguiam se preparar antes por causa da reunião imediatamente anterior, e essa reunião anterior também tinha vindo de outra. Em teoria, dá para criticar dizendo que bastaria reduzir o número de reuniões, mas, na prática, essas reuniões tinham valor e, mesmo incluindo o tempo de leitura, decisões suficientes eram tomadas. No fim, é preciso focar no resultado, e parece que na Amazon as vantagens desse método são consideradas maiores que as desvantagens
  • Fico em dúvida sobre por que importa tanto quando o documento é lido. Se for preciso mais tempo, dá para aumentar a duração da reunião. A desvantagem seria a dificuldade maior de encontrar um horário, mas, no total, o tempo gasto não muda
  • Acho que se desperdiça mais tempo quando nem todos estão no mesmo nível de entendimento ou quando existe receio de deixar passar algum corner case
  • Há quem relate a experiência de que, se algo não for tratado de fato na reunião, simplesmente nada acontece
• Há muitos bons conselhos sobre clareza e edição. A fraqueza está em como gerenciar o documento depois que ele é aprovado. Sem manutenção, ele degenera para um estado de "arqueologia de design". Alguns anos atrás, Andrew Harmel-Law propôs os Architecture Decision Records (ADRs) como forma eficaz de registrar decisões de arquitetura dentro da organização, e isso pode ajudar. Os ADRs ficam ao lado do código (por exemplo, adr/001-use-postgres.md) e registram de forma curta o contexto, a decisão e o status. A vantagem é que podem ser revisados facilmente a cada PR e substituídos com facilidade quando a situação muda. Assim, mesmo meses depois, ainda é possível encontrar a justificativa da decisão original. [Link: https://martinfowler.com/articles/…]
  • Nesse modelo, fico me perguntando se comitês da organização inteira, como Security, Privacy e Compliance, virariam revisores em todo PR que incluísse um ADR. Fico na dúvida se um PR assim conseguiria ser mergeado em menos de 90 dias
  • Eu precisaria ler completamente o link da MF.com(https://thoughtworks.com/radar/techniques/…), mas o tal do "Advice Process" termina simplesmente com a frase "fale com todo mundo". Qualquer pessoa com o cargo de "Managing" provavelmente perderia o interesse nesse ponto. O verdadeiro ponto central parecem ser os "quatro elementos de suporte", mas fui ao link para entender melhor ADRs e acabei baixando um PDF(https://thoughtworks.com/content/dam/…). Seria bom se definissem com mais clareza o que exatamente são ADRs
  • O Session messenger é um exemplo representativo. Houve tantas mudanças de design e arquitetura que não existe uma fonte oficial e confiável explicando exatamente como ele funciona. E, se você precisa de mensagens seguras, é melhor simplesmente usar o Signal
• Na minha experiência, organização e clareza são os maiores obstáculos para engenheiros de software melhorarem a escrita de documentos. Acho que a metáfora do autor sobre "código espaguete" é um bom exemplo para explicar a importância de organizar ideias. Já tentei transmitir algo parecido de outra forma, mas pretendo usar essa metáfora no futuro. Já escrevi antes um post de blog parecido (https://ryanmadden.net/things-i-learned-at-google-design-docs/), e achei interessante tanto as semelhanças quanto as diferenças entre empresas, como a densidade de informação e a importância da prática. Quanto à defesa de "parágrafos curtos", penso um pouco diferente. Parágrafos curtos surgem quando a informação foi bem lapidada; apenas quebrar linhas não ajuda muito. Acho que a seção sobre "Editing" explica melhor essa ideia de base
• Tenho um processo que uso. Etapa 1: despejo no documento tudo o que vier à cabeça, de qualquer jeito (até vale tentar ditado por voz). Etapa 2: deixo um LLM (modelo de linguagem de grande porte) tentar organizar a estrutura e o fluxo. Na verdade, posso até descartar o resultado nessa fase; ela faz parte do refinamento contínuo do pensamento. Etapa 3: usando o resultado do LLM como referência, ou montando um novo outline do zero, escrevo o primeiro rascunho. Etapa 4: deixo tudo o mais conciso possível, cortando palavras, trocando por termos mais simples etc. Etapa 5: repito a etapa 4. O LLM funciona como uma ponte que estrutura um rascunho desorganizado. Também é preciso estar disposto a jogar fora o que o LLM produziu. Sempre dá para cortar pelo menos 30%. Sempre me surpreende ver que é possível reduzir sem perder significado
  • Sinto que o processo de editar meu texto novamente é tão importante quanto escrever pela primeira vez. É nesse momento que percebo o quanto cheguei a conclusões apressadas e o que deixei de considerar. Parece que muita gente não valoriza a escrita o suficiente como ferramenta para concentrar o pensamento. Com código é parecido. Mesmo ao escrever algo simples e padronizado, muitas vezes surgem ideias para melhorar o código principal enquanto se escreve o teste. Mas o LLM não aponta esse tipo de oportunidade de melhoria qualitativa
  • É um ciclo de expandir, encurtar, comprimir, expandir de novo e comprimir de novo. Quando alguém faz uma pergunta específica, volto a expandir, e no fim uso o LLM para fazer um resumo leve, mais por diversão. Estamos, no fundo, numa verdadeira montanha-russa sem fim
• Acho que preciso escrever mais. Os principais métodos de estruturação de documentos que conheço são B.O.O. e Good Strategy/Bad Strategy. B.O.O. significa Background, Objective, Overview e serve para organizar o caminho até aqui, além do que se quer mudar e como. Good Strategy/Bad Strategy é um livro estruturado em diagnóstico, diretrizes/pré-condições/requisitos e ações, e, em termos de organização documental, é semelhante ao B.O.O. O B.O.O. funciona bem no Google ou em organizações menores, enquanto Good Strategy/Bad Strategy pode ser aplicado a uma variedade muito maior de escalas, mas exige um autor com boa capacidade de escrita
• Ao fazer uma disciplina de escrita técnica, minha capacidade de resumir pontos-chave com clareza melhorou muito. Foquei no método de "cortar com caneta vermelha" — escrever, riscar e reescrever —, que enfatiza como transmitir um conceito com o menor número possível de palavras. Esse processo tem várias etapas e fica mais fácil quanto mais se pratica. Tento compartilhar essa habilidade com colegas de equipe, mas sempre lembro que é uma competência que precisa ser treinada regularmente
• Gosto muito desse tipo de documento e da própria cultura de escrita em torno dele. Mas também já vi casos em que essa abordagem produz efeito contrário. Explicar as razões e a lógica que levam a uma conclusão é muito eficaz em documentos voltados à persuasão. No entanto, nem sempre esse tipo de convencimento é necessário. Às vezes, escrever a conclusão diretamente logo no início é melhor para o leitor, especialmente para leitores que confiam no autor. Em muitos casos, o leitor quer primeiro saber o ponto principal, em vez de se cansar acompanhando toda a lógica. Depois de conhecer a conclusão, aí sim ele pode querer seguir os detalhes do raciocínio
  • Também funciona muito bem colocar um resumo no topo e deixar os detalhes e fundamentos abaixo
• Às vezes escrevo documentos de design que talvez só eu vá ler. Ainda assim, sinto o poder de simplesmente registrar tudo por escrito. Seria muito útil ter exemplos reais de documentos, para comparar a estrutura dos meus com a estrutura final adotada por outras pessoas