por Angela Zhang
Como um engenheiro de software, eu gasto muito tempo a leitura e a escrita de documentos de design. Depois de ter passado por centenas desses documentos, eu vi em primeira mão uma forte correlação entre bons documentos de design e o sucesso final do projeto.
Este artigo é a minha tentativa de descrever o que torna um documento de design grande.,
O artigo está dividido em 4 seções:
- Por que escrever um documento de design
- o Que incluir em um documento de design
- Como escrever
- O processo de volta
Por que escrever um documento de design?
um doc de design-também conhecido como uma especificação técnica — é uma descrição de como você planeja resolver um problema.
existem muitos escritos já sobre por que é importante escrever um doc de projeto antes de mergulhar em codificação. Então tudo o que vou dizer aqui é:
um Doc de design é a ferramenta mais útil para se certificar de que o trabalho certo é feito.,
O principal objetivo de um Doc de design é torná-lo mais eficaz, forçando-o a pensar através do design e recolher feedback de outros. As pessoas muitas vezes pensam que o objetivo de um Projeto doc é ensinar aos outros sobre algum sistema ou servir como documentação mais tarde. Embora possam ser efeitos colaterais benéficos, eles não são o objetivo em si mesmos.
Como regra geral, se você está trabalhando em um projeto que pode levar um mês de engenheiro ou mais, você deve escrever um doc de projeto. Mas não pare por aí-um monte de projetos menores poderiam se beneficiar de um mini Projeto doc também.óptimo!, Se você ainda está lendo, você acredita na importância dos documentos de design. No entanto, diferentes equipes de engenharia, e até mesmo engenheiros dentro da mesma equipe, muitas vezes escrever documentos de design muito diferente. Então vamos falar sobre o conteúdo, estilo e processo de um bom doc de design.
What to include in a design doc?
um doc de projeto descreve a solução para um problema. Uma vez que a natureza de cada problema é diferente, naturalmente você gostaria de estruturar o seu Projeto doc de forma diferente.,
Para começar, o seguinte é uma lista de seções que você deve, no mínimo, considere a possibilidade de incluir em seu projeto seguinte doc:
Título e Pessoas
O título do seu design doc, o(s) autor (deve ser o mesmo que a lista de pessoas planejamento para trabalhar neste projeto), o revisor do(s) doc (falaremos mais sobre isso no Processo de seção abaixo), e a data em que este documento foi atualizada por último.
visão geral
um resumo de alto nível que todos os engenheiros da empresa devem compreender e usar para decidir se é útil para eles ler o resto do doc., Devem ser 3 parágrafos no máximo.
Contexto
Uma descrição do problema na mão, por que esse projeto é necessário, o que as pessoas precisam saber para avaliar este projeto, e como ele se encaixa na estratégia técnica, estratégia de produto, ou a equipe de metas trimestrais.,
Objetivos e Não-Metas
Os Objectivos seção deve:
- descrever o utilizador orientada impacto do seu projeto, onde o usuário pode ser outra equipe de engenharia ou até mesmo outro sistema técnico
- especificar como medir o seu sucesso usando métricas — pontos de bônus se você pode vincular a um painel de controle que controla essas métricas
Não-Metas são igualmente importantes para descrever quais os problemas que você não vai ser a fixação de modo que todos estejam na mesma página.,
Marcos
uma lista de pontos de controlo mensuráveis, para que o seu PM e o gestor do seu gestor possam contorná-lo e saber mais ou menos quando diferentes partes do projecto serão feitas. Encorajo-o a dividir o projecto em marcos importantes para o utilizador, se o projecto tiver mais de um mês de duração.
Use as datas do calendário para que você tenha em conta atrasos, férias, reuniões, e assim por diante., Ele deve parecer algo como isto:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
Adicionar um subseção aqui se a ETA de alguns desses marco alterações, assim, as partes interessadas podem ver facilmente o mais up-to-date estimativas.
solução existente
além de descrever a implementação atual, Você também deve percorrer um fluxo de exemplo de alto nível para ilustrar como os usuários interagem com este sistema e/ou como os dados fluem através dele.,
Uma história de usuário é uma ótima maneira de enquadrar isso. Tenha em mente que seu sistema pode ter diferentes tipos de usuários com diferentes casos de uso.
solução proposta
algumas pessoas chamam a isto a secção de arquitectura técnica. Mais uma vez, tente passar por uma história de usuário para concretizar isso. Sinta-se livre para incluir muitas sub-seções e diagramas.
forneça uma imagem grande primeiro, em seguida, preencha muitos detalhes. Apontar para um mundo onde você pode escrever isso, em seguida, tirar férias em alguma ilha deserta, e outro engenheiro na equipe pode lê-lo e implementar a solução, como você descreveu.,
soluções alternativas
o que mais considerou ao apresentar a solução acima? Quais são os prós e os contras das alternativas? Já pensou em comprar uma solução de terceiros-ou usar uma de código aberto — que resolva este problema em vez de construir a sua própria?
testabilidade, monitorização e alerta
eu gosto de incluir esta secção, porque as pessoas muitas vezes tratam isto como um pensamento posterior ou saltam tudo juntos, e quase sempre volta para mordê-los mais tarde quando as coisas quebram e eles não têm ideia de como ou porquê.,como é que isto vai aumentar a carga das chamadas e das dev-ops? quanto dinheiro vai custar? causa alguma regressão de latência ao sistema? expõe vulnerabilidades de segurança? quais são algumas consequências negativas e efeitos colaterais? como a equipe de suporte pode comunicar isso aos clientes?
questões abertas
quaisquer questões em aberto que você não tenha certeza sobre, decisões controversas que você gostaria que os leitores pesassem sobre, sugeriu o trabalho futuro, e assim por diante. Um nome descarado para esta secção é o conhecido desconhecido.,
escopo detalhado e cronologia
Esta seção vai ser lida principalmente apenas pelos engenheiros que trabalham neste projeto, seus contatos tecnológicos e seus gerentes. Por isso, esta secção está no fim do doc.
essencialmente, esta é a repartição de como e quando você planeja executar cada parte do projeto. Há muita coisa que vai para scoping com precisão, então você pode ler este post para aprender mais sobre scoping.
tenho tendência a tratar também esta secção do doc de design como um gestor de tarefas de projecto em curso, por isso actualizo isto sempre que o meu escopo estimar muda., Mas isso é mais uma preferência pessoal.
Como escrever
Agora que já falamos sobre o que se passa em um bom design doc, vamos falar sobre o estilo de escrita. Prometo que isto é diferente da tua aula de Inglês.
escreva o mais simples possível
não tente escrever como os trabalhos acadêmicos que leu. Eles são escritos para impressionar revisores de revistas. O seu médico é escrito para descrever a sua solução e obter feedback dos seus colegas de equipa., Você pode alcançar a clareza usando:
- palavras
- frases Curtas
- listas com Marcadores e/ou listas numeradas
- exemplos Concretos, como “Usuário Alice se conecta a sua conta bancária, então …”
Adicionar lotes de gráficos e diagramas
Gráficos muitas vezes, pode ser útil para comparar as várias opções possíveis, e diagramas são geralmente mais fáceis de analisar do que o texto. Tive boa sorte com o desenho do Google para criar diagramas.,
Dica Pro: lembre-se de adicionar uma ligação à versão editável do diagrama sob a imagem, para que possa actualizá-la facilmente mais tarde quando as coisas mudarem inevitavelmente.
incluem números
a escala do problema muitas vezes determina a solução. Para ajudar os revisores a ter uma noção do Estado do mundo, incluem números reais como # of DB rows, # of user errors, latency — e como estas escalam com o uso. Lembras-te das tuas notas grandes?
tente ser engraçado
A spec não é um artigo acadêmico. Além disso, as pessoas gostam de ler coisas engraçadas, então esta é uma boa maneira de manter o leitor ocupado., Mas não exageres ao ponto de te afastares da ideia central.
Se você, assim como eu, tem dificuldade de ser engraçado, Joel Spolsky (obviamente, conhecido por seus talentos cômicos…) tem esta sugestão:
Uma das maneiras mais fáceis de ser engraçado é ser específico quando ele não é chamado para, em Vez de dizer “interesses especiais” dizer “canhoto chouriço agricultores.”
Faça o teste cético
Antes de enviar o seu documento de design para outros para rever, passe por ele fingindo ser o revisor. Que perguntas e dúvidas você pode ter sobre este projeto?, Então, trate-os antecipadamente.
Faça o teste de férias
Se você vai em férias longas agora, sem acesso à internet, alguém em sua equipe pode ler o doc e implementá-lo como você pretendia?
O principal objetivo de um Doc de design não é a partilha de conhecimento, mas esta é uma boa maneira de avaliar a clareza para que outros possam realmente dar-lhe feedback útil.
Process
Ah yes, the dreaded P-word., Os documentos de Design ajudam você a obter feedback antes de perder um monte de tempo implementando a solução errada ou a solução para o problema errado. Há muita arte em obter um bom feedback, mas isso é para um artigo posterior. Por agora, vamos apenas falar especificamente sobre como escrever o Projeto doc e obter feedback para ele.em primeiro lugar, todos os que trabalham no projecto devem fazer parte do processo de concepção. Não faz mal se a tecnologia conduzir muitas das decisões, mas todos devem estar envolvidos na discussão e comprar o design., Então o ” você “ao longo deste artigo é um” você ” realmente plural que inclui todas as pessoas no projeto.
Em segundo lugar, o processo de design não significa que você olhar para as ideias de teorização do quadro branco. Sinta-se à vontade para sujar as mãos e protótipo de soluções potenciais. Isto não é o mesmo que começar a escrever código de produção para o projeto antes de escrever um Doc de design. Não faças isso. Mas você deve absolutamente se sentir livre para escrever um código hacky descartável para validar uma ideia., Para garantir que você só escreve código exploratório, Faça com que seja uma regra que nenhum deste código protótipo seja fundido para dominar.
Depois disso, à medida que você começa a ter alguma idéia de como ir sobre o seu projeto, faça o seguinte:
- peça a um engenheiro experiente ou técnico líder em sua equipe para ser o seu revisor. Idealmente, este seria alguém que é bem respeitado e / ou familiarizado com os casos extremos do problema. Suborná-los com o boba, se necessário.vai para uma sala de conferências com um quadro branco.,
- descreva o problema que você está enfrentando para este engenheiro (este é um passo muito importante, não pular isso!).
- então explique a implementação que você tem em mente, e convencê-los que esta é a coisa certa a construir.
fazendo tudo isso antes mesmo de começar a escrever o seu Projeto doc permite-lhe obter feedback o mais rápido possível, antes de investir mais tempo e se apegar a qualquer solução específica., Muitas vezes, mesmo que a implementação permaneça a mesma, seu revisor é capaz de apontar casos de Canto que você precisa cobrir, indicar quaisquer áreas potenciais de confusão, e antecipar as dificuldades que você pode encontrar mais tarde.
então, depois de ter escrito um rascunho de seu Projeto doc, Faça com que o mesmo revisor leia novamente, e carimbá-lo de borracha, adicionando seu nome como o revisor na seção Título e pessoas do Projeto doc. Isso cria incentivo adicional e responsabilidade para o revisor.,nesta nota, considere a adição de revisores especializados (tais como SREs e engenheiros de segurança) para aspectos específicos do projeto.depois de você e o(s) revisor (es) assinarem, sinta-se à vontade para enviar o documento de design para sua equipe para comentários adicionais e compartilhamento de conhecimento. Sugiro que o tempo limite este processo de recolha de feedback para cerca de uma semana para evitar atrasos prolongados. Comprometa-se a responder a todas as perguntas e comentários que as pessoas saem dentro dessa semana. Deixando os comentários Pendurados = mau karma.,por último, se houver muita discórdia entre si, o seu revisor e outros engenheiros que lêem o doc, recomendo vivamente a consolidação de todos os pontos de discórdia na secção de discussão do seu doc. Em seguida, organize um encontro com as diferentes partes para falar sobre essas divergências pessoalmente.
sempre que um tópico de discussão tem mais de 5 comentários, mover-se para uma discussão em pessoa tende a ser muito mais eficiente. Tenha em mente que você ainda é responsável por fazer a chamada final, mesmo se todos não podem chegar a um consenso.,
Em falar com Shrey Banga recentemente sobre isso, eu aprendi que a Quip tem um processo semelhante, exceto além de ter um engenheiro experiente ou em tecnologia para levar o seu time como um revisor, eles também sugerem ter um engenheiro em uma equipe diferente revisão doc. Eu não tentei isso, mas eu posso certamente ver isso ajudando a obter feedback de pessoas com diferentes perspectivas e melhorar a legibilidade geral do doc.
Uma vez que você fez tudo o acima, tempo para começar a implementação!, Para pontos de brownie extra, Trate este doc design como um documento vivo à medida que você implementa o projeto. Atualizar o doc sempre que você aprende algo que leva a você fazer alterações na solução original ou atualizar seu escopo. Vais agradecer-me mais tarde quando não tiveres de explicar as coisas vezes sem conta a todas as tuas partes interessadas.
finalmente, vamos ficar realmente meta por um segundo: como avaliamos o sucesso de um Doc de design?o meu colega Kent Rakip tem uma boa resposta para isto: um Doc de design é bem sucedido se o ROI certo do trabalho for feito.,o ts da arquitetura técnica
X é o mais arriscados parte do projecto de arquitecturaX primeiro de risco do projetoX não é possível ou muito mais difícil do que você originalmente destinadosNo início deste artigo, dissemos que o objetivo de um design doc é fazer com que o direito do trabalho é feito., No exemplo acima, graças a este Projeto doc, em vez de desperdiçar potencialmente meses apenas para abortar este projeto mais tarde, você só passou 8 dias. Parece-me um resultado bem sucedido.por favor, deixe um comentário abaixo se tiver alguma dúvida ou feedback! Também gostava de saber como é que desenhas docs de forma diferente na tua equipa.dando crédito onde o crédito é devido, eu aprendi muito do acima trabalhando ao lado de alguns engenheiros incríveis no Xadrez (estamos contratando! Venha projetar e construir alguns sistemas técnicos doces conosco) e Quora.,se você gosta deste post, siga-me no Twitter para mais posts sobre engenharia, processos e sistemas de infra-estrutura.