Uma nova proposta: discutir Comunicação Técnica

Documentação é um dos principais obstáculos na carreira da maioria dos desenvolvedores em qualquer empresa. Seja por detestarem escrevê-la, seja por se descobrirem entre a cruz e a espada quando o problema que precisam resolver deveria ter sido documentado anteriormente. 

No entanto, todas as partes são corresponsáveis por este problema: as faculdades quase nunca ensinan alunos a escreverem documentação curta e eficaz (de fato, a lição que me ensinaram foi o oposto); desenvolvedores colocam a documentação sempre como a última das suas prioridades (esta foi minha experiência em todas as empresas por que passei, inclusive a atual); empresas frequentemente se recusam a enxergar o tempo gasto com documentação como produtivo; e os poucos gestores que se importam tendem a transformá-la numa tarefa administrativa, colocando-a sob a responsabilidade de colaboradores que pouco entendem do workflow de produção de código útil.

Vou começar com um exemplo polêmico: a documentação do Django é considerada um exemplo a ser seguido. De fato, é tão completa e detalhada que, quando decidi abandonar o WordPress, uma das minhas prioridades para o CMS do meu novo blog era ser construído sobre o Django. Bom, esta característica é realmente fantástica para alguém que acabou de começar a desenvolver aplicativos para a web. O único problema é que usuários que leem documentação não permanecem inexperientes por muito tempo. Em poucos meses, ler a documentação do Django tornou-se mais irritante do que produtiva. Hoje em dia, apesar de agradecer a todos que dedicaram seu tempo e seu esforço a escrever aquelas linhas, prefiro simplesmente ir ao Stack Overflow e procurar uma resposta direta

Por outro lado, comecei a brincar com uma ferramenta de visualização de dados chamada Bokeh. Parece ser uma ferramenta muito poderosa para aplicações web em Python, e a maior ameaça ao todo-poderoso Shiny, no momento dominante entre a comunidade científica. Entretanto, enquanto o Shiny é fácil de usar e está diligentemente bem documentado, o Bokeh ainda comete erros amadores, como indicar recursos que já foram removidos

Depois destes dois exemplos, parece-me claro que um problema de toda a comunidade precisará de discussões com toda a comunidade para encontrar a solução menos comprometedora. Um esforço nesta direção seria estabelecer um site do Stack Exchange para Comunicação Técnica, o que, felizmente, já está a caminho, mas necessita da sua contribuição para sair do papel. Se puder, apoie a proposta e ajude-nos a tirá-la da Area 51:

Stack Exchange Q&A site proposal: Technical Communication

No momento, já percorremos 63% do caminho para virar um beta online, estamos quase lá. No entanto, uma vez que o site seja aprovado, virará um fórum privado por algumas semanas, acessível somente aos que apoiaram a proposta. Em outras palavras, o momento de entrar é agora!

Etiqueta: stack exchange tools 

 

Comentários

Não há comentários no momento.

Novo Comentário