Especificações Funcionais Menos Dolorosas

Tempo médio de leitura: 10 minutos

Créditos da imagem: New York Public Library

Qualquer leitor experiente sabe reconhecer o quão será incrível a leitura de um artigo somente pelo peso do nome do autor.

Como desenvolvedor, ao encontrar a recomendação de posts sobre como escrever especificações funcionais do Joel on Software, eu já esperava uma grande aula de como fazer, e foi justamente o que aconteceu!

Disclaimer: Este post é uma releitura, tradução e resumo de um artigo. Para maiores detalhes técnicos, consulte a série de posts originais.

Quem esse porra louco que você paga pau?

Esse é o cara :P

O Joel é um puta cara do meio de tecnologia(e muito conhecido no mundo .NET), ele é simplesmente o CEO do StackOverflow, ele também cofundador da Fog Creek Software, a empresa que criou o Trello. O cara manja pra caraleo de tecnologia, mas também muito de negócio(bagarai!), e tudo que envolve internet, você pode encontrar mais informações sobre ele nessa página:

Em uma série de 4 posts, Joel consegue analisar o processo de desenvolvimento de uma boa especificação funcional de software, e também recomenda o que não fazer.

Mas afinal, que raios é uma especificação funcional?

Uma especificação funcional descreve como produto funcionará totalmente da perspectiva do usuário. Essa documentação não se importa com como as coisas serão implementadas, quais algoritmos ou banco de dados serão usados. É uma conversa sobre features, ela especifica como as telas funcionam o que elas fazem, além de menus, caixa de diálogos, interações com o usuário e por aí vai…

Aqui tem um exemplo bem bacana de uma especificação funcional, criada pelo Joel(só pra você saber, esse cara escreveu várias documentações dos projetos da Microsoft(Excel, Access), lá em 1995..enquanto você assistia o Mamonas Assasinas botando pra fuder em qualquer canal de televisão..eles eram fodas, ops, vamos parar por aqui.)

Vamos falar sério entonces

Abaixo, eu fiz uma tradução e releitura do que o Joel diz em 4 posts(todos os links estão no final desse artigo), eu demorei cerca de 2 horas para ler tudo, mais 1 hora e pouquinho pra conseguir resumir e traduzir, peguei o que considerei mais importante e tentei transformar numa leitura mais de boas, você deve ser capaz de ler tudo em cerca de 10 minutos.

Na primeira parte, é introduzido a importância de uma especificação funcional para um projeto de sucesso. Entre uma brincadeira e outra(a leitura é sempre confortável), Joel questiona:

Por que se preocupar com uma especificação funcional?

De forma sucinta, a resposta é: salvar MUITO tempo de comunicação que poderia estar sendo investimento em estar construindo o seu projeto fodastico.

Quando você escreve uma especificação, você só precisa explicar como o software funciona uma única vez, depois disso todo mundo da equipe pode simplesmente ler a especificação.

  • O pessoal de QA lê e já fica sabendo como o software deve funcionar, assim eles sabem o que testar.
  • A galera pirada do marketing, vai ter que segurar a emoção pois agora eles sabem exatamente o que é esperado do produto, assim podem criar as páginas sobre o projeto que ainda não existe, mas com mais assertividade.
  • O time de desenvolvimento de negócio simplesmente vai fingir que não leu a especificação e vai distorcer QUASE tudo para vender o produto, vão fantasiar que produto cura a calvíce, que combate verrugas…esse tipo de coisa, mas tudo bem, tudo OK, porque é isso que vai trazer os investidores(R$$$$, como já diz o Pink Floyd na música Money: “Money, it’s a gas.”)
  • Os nerds do time de programação, agora sabem exatamente que código terão que escrever.
  • Os malas dos clientes irão ter certeza que os desenvolvedores estão construindo um produto que eles realmente desejam comprar
  • Os editores técnicos(quem escreve aqueles manuais bem chatos), podem ler e escrever um manual bem mais caprichado. (que eventualmente será esquecido e jogado num baú HAHAHAH)
  • Os fanfarrões dos gerentes podem olhar e saber o que está acontecendo nas reuniões de planejamento e gestão.

Quando você não tem uma especificação, tudo isso listado acima ainda acontece, mas agora vai ser durante o cafezinho, ou será necessário mais uma reunião chata pra cacete, ou então as pessoas vão precisar interromper uma às outras durante o desenvolvimento, o cara de Q&A vai infernizar a vida do desenvolvedor, e não só ele, mas também os editores técnicos, e até mesmo o pessoal do marketing, pois eles precisam saber o que esperar para poderem vender para os clientes. Isso vai acabar com a felicidade e disposição da sua equipe, desenvolvedores irão ficar PUTOS . DA VIDA e irão reclamar para seus superiores, que agora proíbem outras pessoas de falarem com os devs….e isso tudo vai resultar numa puta bosta de projeto, pode acreditar.

Falta de especificações vai fuder seu planejamento e levar todo seu dinheiro

Só coloquei essa imagem [sem contexto] aqui para enganar seu cérebro quando você der scroll para ver o corpo do texto ;)

Porém uma das piores partes de todo esse processo é: VAI SER IMPOSSÍVEL TER UM PLANEJAMENTO EFETIVO!

Beleza, você não vê nenhum problema em não ter que planejar a sua vida, o seus projetos pessoais, ou aquela sua viagem pro interior no carnaval…mas isso não é verdade para empresas reais, porque desenvolver um produto custa dinheiro, algumas vezes muito dinheiro, então como você imagina que um negócio vai conseguir planejar sua estratégia e custo se ninguém faz a MINIMA IDEIA REAL(não venha me falar de estimativas que saíram da sua mente ao caso, ela irá falhar) de quando o software estará pronto e quanto ele custará?
Sem planejamento, é impossível ter uma noção de quanto tempo você irá precisar tirar dinheiro do caixa para pagar pessoas para desenvolver o produto…então boa sorte gastando toda suas economias em um projeto mal planejado, depois não adianta reclamar que o curso do Sebrae não foi legal.

O que uma especificação funcional deve conter?

Uma introdução/disclaimer

Como o Joel freeza, essa é uma medida totalmente auto preventiva, isso implica em escrever coisas como: “Essa documentação ainda não está completa” isso por exemplo vai evitar que neguinho fique batendo toda hora nas suas costas para perguntar coisas, eles saberão que a documentação está evoluindo.

Um autor, 1 autor

Isso mesmo, essa ideia de que coisas devem ser escritas juntas é uma furada, às pessoas NÃO GOSTAM DE ESCREVER, elas mais gostam de ler, agora imagina colocar um bando de gente que não gosta de escrever para juntos montarem uma documentação. E isso não tem nada a ver com egoísmo ou não fazer um bom trabalho em equipe, ou então permitir que uma pessoas tome créditos por uma especificação por ter o nome dela, NONSENSE. As pessoas devem ter responsabilidade e ownership(mais legal que propriedade) sobre coisas que são específicas para ela. Se algo está errado na especificação, bom você já sabe com quem falar né? É dever e responsabilidade dessa pessoa corrigir isso, pronto, simples, efetivo.

PS: Se for necessário envolver muitas pessoas para escrever uma documentação, separe por áreas, e delegue uma pessoa de cada área para escrever a sua parte.

Cenários de utilização

Certamente você tem na sua cabeça cenários de como as pessoas vão usar seu produto, certo? Então escreva elas, de forma simples separe seus “grupos” de audiência(seus usuários) e então crie cenários típicos, mas totalmente fictícios, e escandalosamente estereotipados(SIM!) de como irão utilizar seu produto. Quanto mais vívido e realista for o cenário, melhor será o trabalho da sua equipe ao desenvolver um produto para usuários reais e/ou fictícios

O que não iremos fazer

Cara, só deus sabe em como todo mundo adora dar palpites quando estamos desenvolvendo um novo produto, claro, todos querem ver a sua feature favorita, ou aquela que que eles não podem viver sem implementada. Se você fizer todas, vai levar tempo infinito, e seu dinheiro vai acabar :P Para isso, uma seção com as coisas que não iremos fazer, isso provavelmente irá gerar discussões, mas é importante se livrar disso o quanto antes. “Não iremos fazer, obrigado”, é o que você irá dizer.

Um overview

Uma indice, uma imagem, algo que dê uma visão geral do que aquele documento tem pra oferecer. Todo mundo irá ler isso, e então os detalhes farão mais sentido.

Detalhes, detalhes, detalhes.

Dê nome para as telas, deixe explícito como deve ser o comportamento frente a um determinado erro. Ex: Se o email do usuário for inválido, o que deve acontecer? E se o usuário for menor de idade? Isso tudo deixa claro as decisões que foram feitas, se não estiverem decididas, não será possível escrever código, a especificação deve documentar as tomadas de decisões

Side Notes

É horrível ter que ler uma documentação e ter que lidar com os termos técnicos que são somente importantes para uma determinada equipe. E você pode usar sidenotes para falar com essa galera, manda bala, escreva o que tiver que escrever para os designers, desenvolvedores, equipe de marketing em sidenotes, assim você otimiza a leitura da sua especificação, e só ocupa quem realmente precisa ler aquelas notas

Especificações precisam ser mantidas

Decidi somente traduzir o que o Joel diz:

Alguns times de desenvolvimento adotam uma mentalidade “cascata”: Nós vamos desenvolver o programa de uma vez, escrever uma especificação e então jogar ela por cima do muro para os outros desenvolvedores e ir pra casa. Tudo que eu tenho pra dizer sobre isso é HAHAHAHAHAAHAHAHAHAHAHAHAHAHAHAAHAHHAAHAHAHAHAHAHA!

É por causa de abordagens como essa que especificações tem uma reputação tão ruim. Muitas pessoas sempre dizem para mim: “Especificações são inúteis, ninguém segue elas, elas estão sempre desatualizadas, e nunca refletem o produto”

Me desculpe. Talvez suas especificações sejam desatualizadas e não reflitam o produto. Minhas especificações são sempre atualizadas. E a atualização continua de acordo com o desenvolvimento do produto. A especificação sempre reflete nosso melhor entendimento coletivo do que como um produto irá funcionar. A especificação somente é congelada quando o desenvolvimento acaba, isto é, quando o código está completo.

Na terceira parte o Joel discute como fazer, ele sugere a contratação de um Program Manager e conta uma história peculiar da Microsoft sobre como um cara mutcho louco decidiu criar a estrutura de “Master programmers” e “code slaves”, vai lá pra dar uma lida melhor nisso. Ele também dá dicas de como não contratar um program manager, como por exemplo: Não transforme um desenvolvedor em program manager, desenvolvedores geralmente tem habilidades totalmente . contrárias a que um program manager deve ter, ele cita o clássico caso de Peter Principle : As pessoas tendem a serem promovidas para seu level de incompetência. Outras dicas podem ser obtidas direto no artigo, ou mais abaixo.

Dicas

Eu fiz isso novamente, espero que tenha funcionado

Na última e uma das mais interessantes partes dessa série, o Joel faz um estudo sobre humanos e sua incapacidade de ler muitas páginas de texto puro, formal, chato, tedioso, ahhhhh. Ele diz que você tem ILUDIR as pessoas para REALMENTE lerem de suas coisas, se você é humano(e eu espero que seja), você deve saber que isso faz todo sentido! Geralmente, para “enganar” as pessoas é só questão de boa escrita, abaixo algumas dicas para que você realmente consiga engajar as pessoas na leitura das suas paradas, segue:

1 — Seja engraçado

Eu adorei isso! O Joel é um cara muito do nível enterprise(ou foi), e ele tem uma visão muito bacana sobre isso. Ele diz que você tem que fazer a experiência de leitura ser agradável, e diz: “Não venha me dizer que você não nasceu engraçado, pq todo mundo tem ideias engraçadas todo o tempo, elas só não falam porque acham que as outras pessoas vão considerá-las pouco profissionais. Algumas vezes você tem que quebrar as regras” E isso nos leva para uma das coisas mais incríveis que eu já li sobre ser engraçado:

Se você acha falta de profissionalismo ser engraçado, então me desculpe, mas é você que não nenhum senso de humor. (não negue, pessoas sem senso de humor sempre negam! Mas você não pode me enganar) Mas em todo caso, se você trabalha em uma empresa onde as pessoas irão te respeitar menos porque você é um cara maneiro e escreve especificações engraçados, brisentas e agradáveis de serem lidas, então vá procurar outro lugar para trampar cara, porque a vida é MUITO CURTA para perder horas do seu dia em um lugar tão severo e miserável.

Palmas Joel, palmas cara, você é o cara! :clap: :clap:

2 — Escrever especificações é como escrever código para o cérebro compilar

Essa é uma parte mais chata de traduzir, e eu tô com preguiça e não acho TÃO essencial, mas se você quiser(e eu recomendo), vai lá no blog dele ler melhor sobre isso.

3 — Seja um cara simples

Não use linguagem formal só porque você acha que vai parar pouco profissional se não usar termos complexos e difíceis, use a linguagem mais simples que você puder.

Se você tiver problemas escrevendo uma sentença, quebre ela em partes, e sempre evite muros de textos, isso assusta as pessoas e elas não irão ler. Ou você se lembra da ultima vez viu um artigo em alguma revista ou jornal popular que é SOMENTE composta por texto? As revistas ultrapassam tanta essa barreira que elas adicionam “quotes” do próprio artigo e inserem no meio da página, numa fonte gigante, justamente para evitar a aparência de uma página cheia de texto. Use lista numeradas, listas, imagens, gráficos, tabelas, e uma caralhada de espaços em branco para que a leitura “pareça”(só vai parecer mesmo, mas isso é suficiente) mais fofinha :P

Nada melhora tanto uma documentação quanto uma porrada de screenshots, como já dizem: UMA IMAGEM VALE MAIS QUE MIL PALAVRAS, e por falar nisso, se você não sacou a ideia sobre as revistas inserirem citações no meio do texto, veja essa imagem e tudo ficará claro na sua cabeça, pode crer.

(Pare por um momento e imagine essa leitura sem imagens, seria totalmente CHATA, ninguém iria ler esse conteúdo maravilhoso, mas thanks god Tim Urban é um gênio e pessimo desenhista HAHAH )

4 — Revise, e releia várias vezes

Bom, essa é meio óbvia, então faça! Quando você encontrar uma sentença que considerar difícil de entender, refatore, reescreva.

5 — Templates são considerados ruins

Como eu acredito que essa dica não se aplica a todo tipo de empresa, não vou gastar mais do seu tempo com isso, mas novamente você pode ir lá no post e ler

Referências

Eu gostei dessa ideia!

Ufa! Acabou, agora você já pode voltar a sua rotina normal \o/

Abaixo os links dos posts originais em inglês.

Parte 1 — Especificações menos dolorosas: Porque se importar

Parte 2 — Especificações menos dolorosas: O que é uma especificação

Parte 3 — Especificações menos dolorosas: Mas como fazer?

Parte 4 — Especificações menos dolorosas: Dicas

Show your support

Clapping shows how much you appreciated Rafael Fidelis’s story.