 |
| (Eu sou desenvolvedor e odeio documentação) |
Este sentimento é comum entre a comunidade de desenvolvedores. Certamente todos se esforçam para ser um bom desenvolvedor de software, mas honestamente, a documentação não é a parte favorita de ninguém.
A era da complexidade começou muito atrás, quando o software tornou-se uma realidade. Tudo é bem simples no início, mas o verdadeiro problema começa quando os usuários usam o software (é claro que foi criado para eles, mas mesmo assim). Novos membros da equipe que precisam entender o produto também impulsionam a necessidade de documentação. Para os novos membros de equipe que desempenham papéis de desenvolvimento de software, uma documentação de código apropriada é a única maneira de começar a entender o software.
Escrever, por outro lado, é uma habilidade severamente ignorada em todo o mundo. Muitos estudantes e profissionais acham difícil construir frases bem estruturadas e parágrafos. Um interessante artigo em SmartBear analisa o impacto positivo da escrita para desenvolvedores de software.
No entanto, no mundo do Vale do Silício ou outros centros de TI, a documentação é provavelmente o aspecto mais odiado do desenvolvimento de software. É tão odiado que, por vezes, os desenvolvedores de software encontram razões estranhas não para documentar seu projeto.
Pode haver várias razões para este comportamento estranho. Vamos discuti-las abaixo.
Por que os desenvolvedores escrevem documentações horríveis
Uma documentação pobre é um cenário comum na maioria dos projetos de desenvolvimento de software. Pode haver muitas razões, tanto lógicas quanto ilógicas para que isto ocorra. Mas qual o problema? Vamos analisar mais profundamente.
Os desenvolvedores estão muito próximos dos Projetos
Isto pode parecer romântico, mas a verdade é que a maioria dos desenvolvedores está muito perto de seu projeto para considerarem escrever documentação sobre ele. Um artigo em Writing Assist discute os impactos das relações estreitas que dificultam a documentação escrita. O impacto é sentido pelos outros membros da equipe, os usuários finais, ou a empresa com quem eles estão lidando – os desenvolvedores não estão pensando nos outros, e, portanto, não estão explicando as coisas com clareza suficiente para os leitores da documentação. Mesmo que esse ponto pode ser contestado por alguns céticos, é difícil negá-lo completamente. A intrincada relação que os desenvolvedores têm com o seu código às vezes pode levá-los a escrever uma documentação pobre porque eles estão em uma posição onde entendem o que está acontecendo e não enxergam a necessidade de explicar as coisas tão claramente quanto possível.
Sem a Necessidade de Escrever a Documentação
Muitos desenvolvedores não sentem a necessidade de escrever a documentação. Pelo contrário, há sempre uma maneira de abordar um problema, seja escrevendo ou programando, mas este não é o caso aqui. Quando se insiste para que eles o façam, esses desenvolvedores escrevem uma documentação ruim, pois simplesmente não estão interessados na tarefa. O resultado final? Desenvolvedores descontentes, com uma documentação terrível que só eles conseguem entender.
Os Desenvolvedores não Precisam de Documentação
A ideia aqui vem como consequência do primeiro ponto. Se você é um desenvolvedor, então você provavelmente sabe as razões por trás deste tipo de pensamento. É simples. Desenvolvedores entendem no que eles estão trabalhando e é por isso que optar por ignorar a documentação. Parece razoável, certo? No entanto, os mesmos desenvolvedores podem esquecer os meandros de seu próprio trabalho quando tiverem que revê-lo depois de algumas semanas, meses ou anos. Além disso, sem a devida documentação ou comentários em seu código, tanto a manutenção e comunicação acabam ficando complexas.
Documentação exige tempo e esforço
Escrever não é uma tarefa fácil; ela requer pensamento crítico, paciência e esforço. Para os desenvolvedores, a documentação pode ser uma tarefa árdua. De acordo com muitos, é apenas um desperdício de tempo e esforço, eles já sabem que é necessário um tempo significativo para produzir boa documentação. Desenvolvedores preferem usar esse tempo e esforço na implementação de novas funcionalidades, na solução de problemas, ou tratando erros.
Pressão Para Entregar o Projeto no Prazo
Há sempre uma data de entrega prevista. O desenvolvedor precisa para entregar o projeto no tempo, e ninguém se preocupa com a documentação. A empresa quer entregar o projeto o mais rápido possível por causa das exigências do cliente, e a primeira coisa que vai pelo ralo é a documentação. A única exceção é quando o cliente menciona explicitamente a necessidade de documentação.
Os p
rogramadores são Preguiçosos
Mesmo com habilidades suficientes para escrever uma boa documentação, muitos programadores optam não fazer isto. Às vezes, a razão é pura preguiça. Não há muito para refletir sobre este ponto, mas este é o tipo de programador que está motivados simplesmente pelo pagamento, e portanto, não se envolve nessas atividades que não lhes geram mais dinheiro.
Desenvolvimento e Escrita são duas Habilidades Diferentes
Então, imagine que você é um desenvolvedor (se você estiver lendo isso, você provavelmente é) e gostaria de programar coisas. Isto exige raciocínio lógico e espacial – traços que são muitas vezes mais matemáticos do que qualquer outra coisa. Escrever, por outro lado, requer algumas características semelhantes, mas eles se manifestam de forma bastante diferente. Em suma, a escrita e o desenvolvimento são duas habilidades diferentes, que requerem diferentes processos de domínio e de pensamento.
De acordo com um interessante artigo no Atlantic, o autor Bernard Meisler escreve: “A maioria dos engenheiros não consegue escrever uma única frase coerente, muito menos encadear um parágrafo. Uma documentação sofrível é a maldição da minha existência.” Bem, isso é muitas vezes verdade para muitos dos desenvolvedores escrevendo sua própria documentação.
Frequentes alterações do código fonte
O desenvolvimento ágil é a nova forma de desenvolvimento. É rápida, implacável, e não incentiva documentação. A razão é simples; o código muda com muita frequência para ser documentado e, portanto, isto conduz ou à uma documentação pobre ou nenhuma documentação!
Arrogância
A arrogância pode levar muitos desenvolvedores a acreditar em não comentar ou documentar o seu trabalho. Mesmo com uma grande capacidade de escrever documentação, muitos programadores optam por não escrever nenhuma documentação que evidencie suas habilidades e assim negam a sua responsabilidade de fazer com que os outros compreendam o seu código.
Auto-Desvalorização
Este ponto é o completo oposto do último. Muitos desenvolvedores que são capazes de escrever documentação não o fazem porque sentem que não são bons o suficiente para escrever. Um usuário do Quora, Daniel Beck, um escritor técnico fala sobre como os desenvolvedores retiram-se da equação por pensar negativamente.
A minha escrita não é boa o suficiente. Meu Inglês é muito ruim. Eu odeio escrever. Não é o meu trabalho. Ninguém lê os documentos. Escrever documentação não é tão importante como escrever o código. Estou ocupado.
Estas são algumas das coisas comuns que os desenvolvedores dizem a si mesmos, se eles estão pensando assim, então é claro que eles vão ter dificuldade para escrever.
E qual será a solução?
Sendo a pobre documentação um grande problema na indústria atual, a plataforma Livecoding.tv se concentra em fornecer uma nova maneira de lidar com a questão. Livecoding.tv é uma plataforma de codificação social para a transmissão ao vivo do desenvolvimento do produto. Qualquer equipe pode utilizar a plataforma para gravar o seu processo de desenvolvimento e torná-lo privado apenas para uso interno. Projetos de código aberto podem se beneficiar ainda mais da plataforma, melhorando o processo de colaboração.Então, como é que você lida com os problemas de documentação atuais? Documentação em vídeo é a resposta. O desenvolvedor registra seu trabalho, para ser consultado por outros membros da equipe ou por um potencial escritor técnico que trabalha com a documentação do projeto.
A documentação em vídeo é uma abordagem melhor do que a documentação escrita, uma vez que não requer nenhum esforço extra do desenvolvedor. Todos os estágios de desenvolvimento podem ser armazenados em vídeo e acessados sempre que necessário. A coisa boa é que os novos membros da equipe podem rapidamente se inteirar do projeto com os vídeos gravados e ajuda adequada de outros membros da equipe.
No geral, a ideia é atuar sobre as desvantagens da documentação escrita.
Por outro lado, a equipe ou empresa pode entregar os vídeos para um escritor técnico escrever documentação para usuários finais, o que também economiza tempo. A abordagem também é ideal para equipes ágeis que mudam frequentemente de sua base de código.
Resumo dos Benefícios da Documentação em Vídeo
1. Elimina a necessidade de documentação escrita para a equ
ipe interna.
2. Proporciona uma excelente oportunidade para as equipes ágeis acompanharem as mudanças.
3. Ajuda escritores técnicos a entender melhor.
4. Economiza tempo e esforço dos desenvolvedores, permitindo-lhes focar suas energias para escrever um código melhor e implementação.
5. Pode ser usado para entender os erros de fluxo de trabalho dos membros da equipe e melhorar a produtividade e eficiência.
Artigo: Thiago Freitas
Você tem um artigo ? Envie para: tidadepre@gmail.com
