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