Por que escrever documentos de design de software é importante

Parabéns, você é um desenvolvedor independente competente. De seu começo humilde, talvez trabalhando como testador, você progrediu para um desenvolvedor de equipe, depois um desenvolvedor sênior e agora deu outro salto, o maior de todos, para trabalhar diretamente com clientes.

Mas onde as outras transições eram lineares, esta última era exponencial. Enquanto no passado você recebia suas ordens de um empregador que trabalhava com clientes ou estava no negócio de software, agora todas as responsabilidades que antes eram distribuídas entre testes de especialistas, gerenciamento de programas etc., são todas suas. E agora você está trabalhando com clientes que não estão no ramo de software; eles estão em outro negócio que precisa de um software e não têm uma visão clara e precisa do que querem de você. Este é um desafio muito maior do que parece.

*Nota:* Aqui, estou descrevendo clientes menores que querem um exército de um homem só de seu desenvolvedor. Não é o único caminho que um freelancer pode seguir, e esses não são os únicos clientes com quem trabalhamos na Toptal, mas é o caminho que mais gosto. Claro, se você estiver trabalhando em equipe e não sozinho, alguns dos itens abaixo não se aplicarão. Por exemplo, se você estiver usando metodologias ágeis ou Scrum, provavelmente desejará estruturar seus marcos de maneira um pouco diferente.

Todos vocês já ouviram falar da suprema importância da comunicação. Você não pode trabalhar recebendo algumas frases de descrição concisa pelo Skype e dizendo “Vejo você em três meses quando eu terminar”. Você tem que estar em comunicação com seu cliente e em cada etapa do seu trabalho certificar-se de que você tem ideias congruentes sobre o objetivo, porque é raro que um cliente lhe envie wireframes e uma especificação funcional detalhada. Você terá uma ideia muito geral do que o software deve fazer, parecer e fluir. Se você escrever um aplicativo com base na descrição superficial com a qual geralmente começa, quase não há chance de seu cliente ficar feliz com o resultado. Em cada estágio, você deve iterar até chegar a um acordo.

Tendo trabalhado por anos em empresas que também atuavam no ramo de software, onde todos da equipe eram da mesma cultura, falavam a mesma língua nativa, trabalhavam no mesmo corredor, se encontravam diariamente etc. a empresa ainda não conseguia o que queria na metade do tempo. Não se engane: o desafio aqui é enorme.

Por que os documentos de design de software são importantes

Portanto, quando você assume um novo projeto, antes mesmo de abrir o Xcode ou o Visual Studio, você precisa ter metas de design claras e acordadas . E essas metas devem ser estabelecidas em um documento de especificação. Se o cliente não tiver escrito um, você deve escrevê-lo e enviá-lo para revisão antes mesmo de abrir seu IDE. E se você encontrar um cliente que diz: “Não temos tempo para documentos de design”, com franqueza, você deve se afastar do projeto porque tem problemas pela frente. A especificação não precisa ser particularmente longa; pode ser apenas algumas páginas, mas no mínimo deve definir a interface do usuário, incluir wireframes (se houver um componente de interface do usuário) e definir marcos de conclusão.

Sem este documento, você acabará em um ciclo de equívocos amargos, clientes contestando o que disseram a você ou o que você lhes disse, enviando com raiva recortar e colar de comunicações anteriores, interpretando e discutindo até chegar o momento em que o cliente exige que você faça alterações para deixar o aplicativo em conformidade com “o que eles realmente pediram” e espera que você faça essas alterações sem pagamento.

Com este documento de design de software, você terá uma resposta para qualquer dúvida: quando surgirem divergências, você pode consultar a especificação com a qual o cliente concordou e assinou, indicando que você a cumpriu ao pé da letra. Em vez de argumentos irados, você fará emendas e esclarecimentos ao documento. Se alguma coisa, o cliente vai se desculpar por deixar a imprecisão escapar em primeiro lugar.

Todos nós queremos clientes satisfeitos. Todos nós queremos uma relação de trabalho amigável. E todos nós queremos o orgulho de um trabalho bem feito. Mas isso não pode ser alcançado se houver qualquer imprecisão sobre o que o trabalho realmente é . Se o seu cliente diz que um documento de design é muito trabalho extra, é seu trabalho explicar a eles que o verdadeiro trabalho extra surgirá quando as revisões precisarem ser feitas devido a algum tipo de mal-entendido. Se o cliente ainda insistir que você avance sem esse documento, você deve aceitar o fato de ter um relacionamento inviável e ir embora.

O que a especificação de design de software deve realmente especificar?

No mínimo, deve ser uma descrição da aplicação desejada, critérios para conclusão e marcos. Lembre-se, você está compartilhando o que é melhor descrito como um documento de requisitos e funções, não uma especificação de implementação. E a menos que uma implementação específica seja um objetivo declarado do cliente, como você faz isso funcionar depende de você.

Interface de usuário

A maioria dos projetos são aplicativos, não bibliotecas ou frameworks. Mas se acontecer de você ter um desses como uma entrega, considere-se sortudo porque a interface do usuário é de longe o componente mais problemático do seu modelo de documento de design e quase sempre leva a mal-entendidos. Muitos clientes lhe enviarão ilustrações perfeitas criadas em um editor gráfico por um designer gráfico que não é programador. Mas o problema é: essas ilustrações não dizem nada sobre animações, estados de controle (por exemplo, Este botão está desabilitado? Ele desaparece quando não pode ser usado?), ou mesmo quais ações devem ser executadas quando um botão é pressionado.

Antes de começar a escrever o código por trás dessas ilustrações, você deve ser capaz de responder a todas essas perguntas. Especificamente, você deve saber:

1. Os controles estão sempre visíveis e/ou habilitados? Em que condições seus estados mudam?
2. Parece um bitmap - é um botão?
3. Que transições ocorrem entre esses estados e visões? E como eles devem ser animados?

Se cabe a você gerar a UI para a simultaneidade do cliente, faça o mesmo ao contrário: use uma ferramenta wireframe e crie um conjunto completo de layouts de tela, incluindo quaisquer variantes que as visualizações mostrem em diferentes estados do aplicativo. Isso pode ser um trabalho exaustivo e tedioso, mas você não vai se arrepender - pode evitar que você reescrever grandes quantidades de código e recriar interfaces devido a um pequeno mal-entendido com grandes implicações. Se você estiver criando um aplicativo duplo (por exemplo, para iPhone e iPad), crie wireframes separados para ambos.

As dimensões da tela também são importantes. Existem (no momento da escrita) três tamanhos de telas do iPhone. Os wireframes separados para telas de 3,5” e 4” provavelmente são excessivos, mas você pode ter que fazê-los; na maioria dos casos, você pode simplesmente alterar as proporções.

Se o seu cliente fornecer gráficos, certifique-se de que eles estejam dimensionados corretamente com as proporções adequadas; transformar qualquer bitmap que tenha texto ou objetos (como círculos) introduzirá distorções. Se eles não corresponderem, peça ao cliente para recriá-los com tamanhos correspondentes. Não presuma que você pode esticar uma tela inicial de 3,5” em uma tela inicial de 4” e apenas rolar com ela.

Funcionalidade

Principais perguntas a serem feitas no documento de design do aplicativo:

• O que o aplicativo faz e com que rapidez ele o faz?
• Quais são as possíveis condições de falha e como elas são tratadas?
• Quais operações únicas são feitas na primeira execução (ou seja, após a instalação)?
• Se o usuário criar entradas de qualquer tipo (por exemplo, marcadores), quais são as limitações?

Generalize essas ideias e seja o mais detalhado e completo possível — porque erros ou mal-entendidos aqui significarão reescrever o código.

Milestones

Seu modelo de especificação deve apresentar marcos claros. Se o seu cliente escrever o design funcional e da interface do usuário, você deverá concordar com um conjunto de marcos. Às vezes, esses também são limites de cobrança, mas, no mínimo, fornecem uma métrica clara para a conclusão. Os marcos podem ser em termos de funcionalidade e/ou componentes; eles podem até ser aplicativos separados se o show envolver um conjunto de entregas. Quando possível, os marcos devem ser aproximadamente iguais em duração.

Exemplo de especificação de design de software

Aqui, farei o layout da estrutura de exemplo de um documento de design adequado. Claro, este modelo deve ser ajustado conforme necessário. Para outro exemplo, consulte a especificação de amostra de Joel Spolsky, com base neste artigo. Ele aborda o documento de maneira um pouco diferente, mas compartilha um sentimento semelhante.

Declaração de Metas

Inclua um pequeno parágrafo descrevendo o projeto e seu público-alvo.

Descrição Funcional

O que o aplicativo faz ? Quais estados do aplicativo (descrições de alto nível dos principais cenários do usuário) o usuário encontrará?

Por exemplo, sua descrição funcional pode ter a seguinte aparência:

• Primeira corrida
• Criando um novo _____ (jogo, pesquisa, etc.)
• Operações
• Comportamento em segundo plano e primeiro plano

Interface de usuário

Inclua wireframes para cada página, com descrições detalhadas de:

• Cada controle, incluindo estados (ativado/desativado/realçado) e operações.
• Orientações e transições suportadas entre eles.
• Funcionalidade representada.
• Manipulação de erros.
• Dimensões e restrições.

Aqui estão os wireframes relacionados ao meu aplicativo iOS mais recente, NotifEye:

Se você estiver interessado, fiz essas maquetes usando a ferramenta de wireframing do Balsamiq.

Por exemplo, a descrição da sua IU pode ter esta aparência:

• Barra de navegação
  • Controle de navegação à esquerda: retornar à página inicial
  • Barra de título: tela atual ou nome da operação
  • Botão Novo: crie uma nova Coisa
• Vista de mesa
  • Seção 0: título da seção
  • Linhas da seção 0:
    • Controle de linha 0 (por exemplo, imagem)
    • Linha de texto 0
    • Linha de texto 2

Milestones

Conforme descrito acima, prazos para conclusão e entregas esperadas.

Por exemplo, a seção de marcos em seu modelo de documento de design pode ter a seguinte aparência:

1. Aplicativo de fachada mostrando a tela e com transições temporárias e imagens/texto de exemplo
2. Protocolo de comunicação: o aplicativo se conecta à rede/servidor
3. Marco Funcional 1: …
4. Aplicativo Alpha (com funcionalidade completa)
5. Estabilidade
6. Liberação

Garantir que a documentação do software permaneça relevante

Não quero dizer que a fase de projeto terminou quando você e seu cliente concordaram com um documento de especificação. Sempre haverá detalhes que nenhum de vocês considerou, e tanto você quanto o cliente, enquanto observam os resultados intermediários, encontrarão novas ideias, mudanças de design, falhas de design inesperadas e sugestões impraticáveis.

O design evoluirá e as alterações devem ser capturadas em seu documento. Em meus 25 anos de experiência, nunca trabalhei em um projeto em que isso não acontecesse – e isso inclui meus próprios aplicativos (ou seja, onde eu era meu próprio cliente). Mesmo assim, criei um documento de projeto com especificações detalhadas e o ajustei conforme necessário.

Acima de tudo, mantenha contato. Pelo menos várias vezes por semana, entre em contato com seu cliente, relate seu progresso, peça esclarecimentos e certifique-se de compartilhar visões idênticas. Como um teste decisivo para sua comunicação, tente garantir que você e seu cliente dêem as mesmas respostas para essas três perguntas:

1. No que o desenvolvedor estava trabalhando?
2. No que o desenvolvedor está trabalhando atualmente?
3. No que o desenvolvedor trabalhará em seguida?