Uncategorized

Por que desenvolvedores escrevem documentações horríveis e como solucionar este problema

Qual é a razão para as documentações pobres que vemos por aí? Falta de interesse, habilidade e tempo? E, por que não utilizar documentação em vídeo?

Este sentimento é comum entre a comunidade de desenvolvedores. Certamente todos se esforçam para ser um bom desenvolvedor de softwares, mas, honestamente, a documentação não é a tarefa favorita.

Documentações são necessárias sempre que há novos membros na equipe de desenvolvimento que precisam entender o produto pois só assim é possível que eles comecem a executar suas funções.

Escrever é uma capacidade severamente ignorada em todo o mundo. Muitos estudantes e profissionais acham difícil construir frases bem estruturadas e parágrafos inteiros.

No entanto, no mundo do Vale do Silício e outros centros de TI, a documentação é provavelmente o aspecto mais odiado do desenvolvimento de software. é tão odiado que, por vezes, desenvolvedores de software arranjam desculpas esfarrapadas para não para documentar seu projeto.

Há várias razões para o comportamento estranho. Vamos discuti-las abaixo.

Por que desenvolvedores escrevem documentações horríveis?

Documentação ruim é um cenário comum na maioria dos projetos de desenvolvimento de software. Pode haver muitas razões, tanto lógicas e não-lógicas para a documentação pobre. Por quê? Vamos aprender mais profundamente.

Os desenvolvedores estão muito apegados aos seus projetos

Isto pode parecer romântico, mas a verdade é que a maioria dos desenvolvedores estão tão apegados ao seu projeto que não escrevem uma documentação adequada. Estes desenvolvedores não pensam no impacto para outros membros da equipe e os usuários finais ao não explicar as coisas com clareza suficiente. Mesmo que esse ponto seja contestado por alguns céticos, é difícil negá-lo completamente. A intrincada relação que desenvolvedores têm com seu código, às vezes, pode levá-los a escrever documentações pobres porque eles estão em uma posição onde eles entendem tudo sobre o programa.

Falta de urgência de escrever a documentação

Muitos desenvolvedores não sentem a necessidade de escrever documentação e quando as pessoas insistem que escrevam a documentação, eles escrevem uma documentação horrível já que não estão interessados na tarefa. O resultado final? Desenvolvedores descontentes com documentação terrível que só eles podem entender.

Desenvolvedores não precisam de documentação

A ideia é o subproduto do primeiro ponto. Se você é um desenvolvedor, então você provavelmente sabe as razões por trás deste tipo de pensamento. É simples. Desenvolvedores sabem no que eles estão trabalhando e é por isso que optam por ignorar a documentação. Parece razoável, certo? No entanto, os mesmos desenvolvedores podem esquecer os meandros de seu próprio trabalho quando eles visitam-no depois de algumas semanas, meses ou anos. Além disso, sem a devida documentação ou comentários em seu código, tanto na manutenção e comunicação acabam sendo prejudicadas.

Documentações requerem tempo e esforço

A escrita não é uma tarefa fácil. Requer pensamento crítico, paciência e esforço. Para desenvolvedores, a documentação pode ser uma tarefa árdua. De acordo com muitos, é um desperdício de tempo e esforço e preferem usar esse tempo e esforço na implementação de novas funcionalidades e resolvendo bugs.

Pressão para entregar o projeto no prazo

Desenvolvedores precisam entregar o projeto no tempo e acaba que ninguém se preocupa devidamente 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.

Programadores preguiçosos

Mesmo com habilidades suficientes para escrever uma boa documentação, muitos programadores optam por não escrevê-la. Às vezes, a razão é pura preguiça. Não há muito para refletir sobre o ponto, mas estes programadores que são motivados simplesmente por cheques de pagamento são os maiores culpados.

Desenvolvimento e escrita são dois conjuntos de habilidades diferentes

Então, imagine que você é um desenvolvedor (se você estiver lendo isso, você provavelmente é) e gostaria de programar coisas. Isso exige raciocínio lógico e espacial que, muitas vezes, envolve mais matemática do que qualquer outra coisa. Escrever, por outro lado, requer outros conhecimentos. Em suma, a escrita e o desenvolvimento são duas habilidades diferentes, que requerem diferentes processos de domínio e de pensamento.

Alterações frequentes de código fonte

O desenvolvimento ágil é a nova forma de desenvolvimento. É rápido, implacável, e não incentiva documentação. A razão é simples: o código a ser documentado muda com muita frequência e, portanto, conduz ou a documentação pobre ou nenhuma documentação.

Arrogância

Arrogância pode levar muitos desenvolvedores a não comentarem ou documentarem o seu trabalho. Mesmo com uma grande capacidade de escrever documentação, muitos programadores optam por não escrever documentação para exibir suas habilidades e dificultar que outras pessoas entendam o seu código.

Autodepreciação

Este ponto é o completo oposto do último. Muitos desenvolvedores que são capazes de documentar não o fazem porque eles pensam que não são bons. Há programadores que reconhecem que escrever não é a sua melhor habilidade e acabam por escrever pouco.

Qual é a solução?

Com pouca documentação sendo um grande problema na indústria atual, o Livecoding.tv fornece uma nova maneira de lidar com essa questão. O Livecoding.tv é uma plataforma social de codificação para a transmissão ao vivo de desenvolvimento de produtos. 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 também se beneficiar da plataforma, melhorando o processo de colaboração.

Então, como lidar com os problemas de documentação atuais? Documentação em vídeo é a resposta. O desenvolvedor registra seu trabalho, apenas para ser explorado por outros membros da equipe ou por um potencial escritor técnico que trabalhará com a documentação do projeto.

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 pegar o projeto com os vídeo gravados e a ajuda adequada de outros membros da equipe. No geral, a ideia é melhorar as desvantagens de documentação escrita.

Por outro lado, a equipe ou empresa pode dar os vídeos para um escritor técnico escrever a documentação para usuários finais, o que também economiza muito tempo. A abordagem também é ideal para equipes ágeis que mudam frequentemente de sua base de código.

Benefícios documentação em vídeo:

  • Elimina a necessidade de ter uma documentação escrita apropriada para a equipe interna.
  • Proporciona uma excelente oportunidade para as equipes ágeis acompanharem as mudanças.
  • Ajuda escritores técnicos para entender melhor.
  • Economiza tempo e esforço para desenvolvedores, permitindo-lhes focar suas energias para escrever um código melhor e implementar recursos.
  • Pode ser usada para entender os erros de fluxo de trabalho dos membros da equipe e melhorar a produtividade e eficiência.

Você é um desses programadores que não gosta de escrever documentação? Por favor, compartilhe seus comentários e deixe-nos saber a sua opinião sobre a documentação em vídeo.

Dr. Michael J. Garbade

I, Dr. Michael J. Garbade is the co-founder of the Education Ecosystem (aka LiveEdu), ex-Amazon, GE, Rebate Networks, Y-combinator. Python, Django, and DevOps Engineer. Serial Entrepreneur. Experienced in raising venture funding. I speak English and German as mother tongues. I have a Masters in Business Administration and Physics, and a Ph.D. in Venture Capital Financing. Currently, I am the Project Lead on the community project -Nationalcoronalvirus Hotline I write subject matter expert technical and business articles in leading blogs like Opensource.com, Dzone.com, Cybrary, Businessinsider, Entrepreneur.com, TechinAsia, Coindesk, and Cointelegraph. I am a frequent speaker and panelist at tech and blockchain conferences around the globe. I serve as a start-up mentor at Axel Springer Accelerator, NY Edtech Accelerator, Seedstars, and Learnlaunch Accelerator. I love hackathons and often serve as a technical judge on hackathon panels.

View Comments

  • Esta é uma péssima ideia.
    Imagine ter que recorrer à um vídeo sempre que precisar ver algo da documentação. Você não saberia os minutos onde estão as coisas que procura, a explicação com certeza será equivalente (ou pior) que uma documentação escrita e ainda há o problema de perda de tempo com edição de vídeo e todo o preparativo para realizar a gravação.
    Fraco.

  • Problemas com essa idéia:

    * Gravar videos leva mais tempo doq escrever (existe um processo enorme de edição).

    * Procurar em video é muito limitado, em texto a busca pode ser especifica.

    * Editar um video desatualizado geraria problemas enormes, editar um texto desatualizado é facil.

    * texto é leve, uma documentação grande não ocuparia muito espaço, em video a documentação teria que ter um bom áudio e video ocupando muito mais espaço.

    * muitos desenvolvedores tem sotaque, dificuldade de fala, e outros problemas que faria a documentação dificil de entender.

    * video ruim teria o mesmo problema de texto ruim.

    Essa idéia gera mais problemas do que soluções.

    ____
    A solução é o que todos ja sabem documentação que faz parte do trabalho, não algo extra que é feito quando se tem tempo e vontade, e codigo limpo e facil de entender deveria ser orgulho de programador.

Recent Posts

Blockchain in Elections: A Leap Toward Transparent Democracy

In 2024 we're witnessing a critical point in democratic technology: the integration of blockchain and…

4 months ago

Win Big with Our Amazon Fire Max 11 & AirPods Pro Giveaway!

We’re thrilled to announce an exciting opportunity for you to win not one but two…

6 months ago

Unleashing Potential: How Education Ecosystem Transforms Learning into Real-World Success

Acquiring practical skills is crucial for career advancement and personal growth. Education Ecosystem stands out…

8 months ago

The Role of Artificial Intelligence in Modern Software Development

Artificial Intelligence (AI) has been making significant strides in various industries, and the software development…

11 months ago

Highest Stable Coin Yields – (W16 – 2024)

Another week to bring you the top yield platforms for three of the most prominent…

12 months ago

LEDU Token OTC Trading

If you hold a large volume of LEDU tokens above 1 million units and wish…

1 year ago