O que há com a aversão à documentação no setor?

Parece haver aversão a escrever até a documentação mais básica. Nosso projeto READMEs é relativamente vazio. Não existem listas de dependências atualizadas nos documentos.

Existe algo que eu não conheço no setor que faz com que os programadores não gostem de escrever documentação? Posso digitar parágrafos de documentos, se necessário, então por que os outros são tão avessos a isso?

Mais importante, como convencê-los de que escrever documentos economizará tempo e frustração no futuro?

Não acho útil especular sobre as motivações de pessoas que não estão adotando algo que você considera uma boa prática ou que continuam fazendo algo que consideram uma má prática. Nesse ramo, as pessoas que se enquadram em uma ou em ambas as categorias superam em muito aquelas com quem você vai se ver, de modo que pare de ficar louco.

Em vez disso, concentre-se no problema e nas possíveis resoluções.

1. Escreva você mesmo uma boa documentação

Pode não ser realista esperar que todos da sua equipe direcionem seus esforços para as coisas que você vê como um problema. Isto é especialmente verdade se você é um novato em relação à equipe. Atrevo-me a supor que você é, porque se você fosse um membro fundador da equipe, parece bastante provável que você já tivesse resolvido esse problema desde o início.

Em vez disso, considere trabalhar em direção ao objetivo de escrever uma boa documentação e levar as pessoas a usá-la. Por exemplo, se alguém da minha equipe me perguntar onde está o código-fonte do Projeto A ou qual configuração especial o Projeto A precisa, eu aponto para a página wiki do Projeto A.

Se alguém me perguntar como escrever uma nova implementação do Factory F para personalizar uma coisa para o Cliente C, digo que está na página 10 do guia do desenvolvedor.

A maioria dos desenvolvedores odeia fazer perguntas que possam fazer com que pareçam não poder "ler o código" ainda mais do que odeiam ler a documentação; portanto, depois de respostas suficientes dessa natureza, eles consultam os documentos primeiro.

2. Prove o valor da sua documentação

Certifique-se de aproveitar todas as oportunidades para apontar onde a documentação está provando seu valor (ou teria, se usada). Tente ser sutil e evite "eu te disse", mas é perfeitamente legítimo dizer coisas como

Para referência futura, a página wiki deste projeto possui informações sobre a ramificação do código principal que foi criado para suporte contínuo da versão 2.1. Portanto, no futuro, podemos evitar a necessidade de fazer um teste de regressão completo se as pessoas que mantêm versões lançadas verificarem o wiki antes de verificar o código.

ou

Estou tão feliz por ter anotado as etapas para executar a Tarefa T. Realmente não me importo se ninguém mais a usa - já me poupou mais tempo do que gastei ao escrevê-la.

3. Obtenha o gerenciamento a bordo

Após alguns incidentes em que a documentação economiza tempo / dinheiro, você provavelmente notará um "degelo" distinto na documentação. Este é o momento de pressionar o ponto, começando a incluir o tempo da documentação em suas estimativas (embora, honestamente, eu geralmente atualize / crie documentos enquanto processos longos estão em execução, como compilações ou check-ins). Especialmente se for uma contratação recente, é possível que isso não seja questionado, mas sim visto como uma nova prática que você está trazendo de um local de trabalho anterior (que pode muito bem ser).

Palavra de cautela: a maioria dos chefes não gosta de fazer as pessoas fazerem nada, especialmente as que não estão diretamente ligadas a uma tarefa faturável, portanto, não espere que esse suporte seja na forma de um mandato. Em vez disso, é mais provável que você tenha rédea relativamente livre para escrever mais documentos.

4. Incentive a documentação ao vê-la

Talvez parte do motivo pelo qual as pessoas não escrevam documentos com a frequência que deveriam seja seja porque sentem que ninguém está lendo. Portanto, quando vir algo de que goste, pelo menos mencione que estava feliz por estar disponível.

Se sua equipe faz revisões de código, é um momento em que você pode inserir uma ou duas palavras sutis para incentivar bons comentários.

Obrigado por documentar a solução alternativa para o bug B no Framework G. Eu não sabia disso e acho que não poderia ter entendido o que você estava fazendo sem isso.

Se você tem alguém da equipe que está realmente entusiasmado com a documentação, não é difícil cultivar essa pessoa indo almoçar ou tomar café e não se esqueça de oferecer uma pequena validação para neutralizar o desânimo que eles podem obter ao ver o resto da equipe. não valoriza tanto a documentação.

Além disso, o problema não é realmente seu, a menos que você esteja em uma posição de liderança ou gerência. Você pode levar um cavalo à água, mas não pode fazê-lo beber. Se não é o seu cavalo, você pode não estar feliz por estar com sede, mas tudo o que você pode fazer é encher a calha.

Existem dois fatores principais na minha experiência:

Prazos

A maioria das empresas é tão orientada pela data que o controle de qualidade, a dívida tecnológica e o design real são reduzidos apenas para que o gerente de projeto não pareça ruim ou atinja um prazo absurdo e prometido para o cliente. Nesse ambiente em que até a qualidade funcional é reduzida, um investimento a longo prazo, como a documentação, tem poucas chances.

mudança

Uma prática recomendada relativamente nova para os desenvolvedores é enfatizar os comentários. A idéia é que manter as informações em dois lugares (o código [incluindo testes] e os comentários ao redor do código) gera muita sobrecarga para mantê-las sincronizadas, com pouco benefício. "Se o seu código é tão difícil de ler que você precisa de comentários, não seria melhor gastar tempo limpando o código?"

Pessoalmente, nem vou mais olhar para os comentários. Código não pode mentir.

A documentação segue a mesma linha. Com a ampla adoção do ágil, as pessoas reconhecem que os requisitos mudam regularmente. Com o amplo uso da refatoração, a organização do código mudará consideravelmente. Por que gastar tempo documentando todas essas coisas que provavelmente mudarão? Código e testes devem fazer um bom trabalho ao fazer isso.

Há vários fatores em jogo aqui:

1. Código bem escrito é sua própria documentação. Sendo todas as outras coisas iguais, é melhor escrever um código mais claro que fale por si, em vez de mais documentação. Faça isso e você precisará modificar menos documentação ao alterar esse código.

2. Escrever documentação é sem dúvida uma habilidade diferente de escrever código. Alguns desenvolvedores de software são melhores nisso do que outros. Alguns são muito melhores em escrever código do que em documentação.

3. A documentação deve ser escrita apenas uma vez , não duas (uma vez no código-fonte e novamente no guia do programador). É por isso que temos coisas como comentários XML e geradores de documentação. Infelizmente, o uso dessas ferramentas pode ser mais complicado e complicado do que escrever a documentação manualmente, e é por isso que você não vê essas ferramentas amplamente usadas.

4. Uma boa documentação é demorada e difícil de executar. Sendo todas as outras coisas iguais, pode haver mais valor para escrever novo código do que escrever documentação para código já existente.

5. Quando o código muda, você também precisa alterar a documentação. Quanto menos documentação houver, menos ela precisará ser alterada.

6. Ninguém lê a documentação de qualquer maneira, então por que se preocupar?

Elefante na sala: programadores não são (necessariamente) escritores. Tampouco são necessariamente passíveis de aprofundar suas implementações para escritores técnicos. Segundo elefante na sala: Os escritores técnicos geralmente não conseguem detalhar detalhes úteis para futuros desenvolvedores (mesmo que os desenvolvedores se dignassem a explicá-los a eles).

Um sistema complexo pode se tornar quase inescrutável ao longo do tempo sem a documentação adequada. O código se torna menos valioso inversamente proporcional à sua capacidade de escrutínio [sic]. Resolvido, o gerenciamento contrata o engenheiro de software que pode ler o código e persuadir os detalhes dos desenvolvedores, paga-o a uma taxa de desenvolvedor e o manda documentar e manter a documentação. Este escritor pode ler o código e saberá quais perguntas fazer e preencherá os detalhes conforme necessário. Assim como você tem um departamento de controle de qualidade, você tem um departamento de documentação interna.

O código se tornará mais valioso, pois você pode licenciá-lo para terceiros (porque ele pode entendê-lo), o código pode ser mais facilmente auditado e aprimorado / re-fatorado, você terá uma melhor reutilização do código, mesmo onde puder facilmente fatorando versões mais leves do seu software, e você poderá introduzir novos desenvolvedores mais facilmente no projeto; seus engenheiros de suporte amarão trabalhar para você.

Isso nunca vai acontecer.

Mais importante, como convencê-los de que escrever documentos economizará tempo e frustração no futuro?

Isso faz isso?

Existem dois tipos de documentação:

Documentação útil

Documenta como usar um produto acabado, uma API, quais endereços IP ou nomes de URL nossos servidores têm, etc. Basicamente, tudo o que é usado pesado e diariamente. Informações erradas serão descobertas rapidamente e serão corrigidas. Precisa ser encontrado fácil e fácil de editar (por exemplo, Wiki online).

Documentação inútil

Documentação que muda frequentemente, poucas pessoas estão interessadas nela e ninguém sabe onde encontrá-la. Como o estado atual de um recurso que está sendo implementado. Ou documentos de requisitos em um documento do Word oculto em algum lugar no SVN, atualizado há 3 anos. Essa documentação levará tempo para escrever e tempo para descobrir que está errado mais tarde. Você não pode confiar neste tipo de documentação. É inútil. Perde tempo.

Os programadores não gostam de escrever ou ler documentação inútil. Mas se você puder mostrar a documentação que é útil, eles a escreverão. Tivemos sucesso com isso em meu último projeto ao apresentar um Wiki, onde poderíamos escrever todas as informações necessárias frequentemente.

Eu diria que o principal motivo é a falta de vontade e a falta de entendimento da função da documentação. Há várias classes de documentação a serem consideradas:

Documentação do produto / release

Isso é tudo que sai com o seu produto 'acabado'. Isso é mais do que apenas manuais, são READMEs, Logs de alterações, HOW-TOs e similares. Em teoria, você pode não escrever isso, mas acaba com um produto que as pessoas não querem usar ou com uma carga de suporte desnecessariamente cara.

Documentação da API

Isso descreve algo que deve ser relativamente estático. Como vários consumidores podem estar codificando para sua API, ela deve ser suficientemente estável o suficiente para que alguma prosa que descreva como usá-la tenha valor. A descrição de quais parâmetros são suportados, qual é o valor de retorno e quais erros podem ser gerados permitirão que outros usuários entendam sua API no nível certo de abstração - a interface ( não a implementação).

Comentários do código

A opinião do setor sobre os comentários parece estar em fluxo no momento. Quando comecei a codificar profissionalmente, os comentários eram sine qua non quando se tratava de escrever código. Agora, a moda é escrever um código tão claro que os comentários são desnecessários. Eu arriscaria um palpite de que isso se deve, em parte, ao fato de muitas linguagens modernas serem escritas em um nível muito mais alto e é muito mais fácil escrever código legível em Java, JavaScript, Ruby etc. do que em assembler , C, FORTRAN, etc. Assim, os comentários tiveram um valor muito maior.

Eu ainda acredito que há valor nos comentários que descrevem a intenção de uma seção do código, ou alguns detalhes sobre por que um determinado algoritmo foi escolhido em detrimento de um mais óbvio (para evitar demônios de refatoração excessivamente zelosos de 'consertar' o código que não '' realmente precisa ser consertado).

Infelizmente, há muito egoísmo, racionalização e auto-ilusão envolvidos nas decisões dos programadores de não documentar. A realidade é que, como o código, o público principal da documentação são outras pessoas. Assim, as decisões de escrever (ou não escrever) a documentação, em qualquer nível, devem ser tomadas no nível da equipe. Para os níveis mais altos de abstração, pode fazer mais sentido ter alguém, além dos desenvolvedores, para fazê-lo. Quanto à documentação no nível dos comentários, deve-se chegar a um acordo sobre o objetivo e a intenção dos comentários, especialmente em equipes de habilidades e experiências mistas. Não é bom ter desenvolvedores seniores escrevendo código que os desenvolvedores juniores não conseguem abordar. Alguma documentação bem colocada e bem escrita pode permitir que uma equipe opere com muito mais eficiência

Aqui estão meus dois centavos.

1. O Agile Manifesto declara "Trabalhando software em documentação abrangente" e nem todo mundo lê para alcançar "Ou seja, embora haja valor nos itens à direita, valorizamos mais os itens à esquerda".

2. Infelizmente, é comum https://en.wikipedia.org/wiki/Code_and_fix e a documentação não funciona com este modelo (fica fora de sincronia).

3. A indústria de desenvolvimento de software não está bem regulamentada. Não há requisito legal para escrever documentação.

4. O código de auto-documentação é a tendência atual.

Dito isto, acho que há muita documentação boa por aí.

A documentação leva tempo e eu suspeito que muitos desenvolvedores tiveram muitos desentendimentos com documentação pior do que inútil. Eles entendem que a documentação não apenas causará problemas ao gerente (o mesmo sujeito que continua cortando a parte do cronograma de controle de qualidade), mas também não ajudará ninguém, inclusive eles.

Qualquer documentação meio decente é um investimento no futuro. Se você não se importa com o futuro (porque não pensa além do próximo salário ou porque acha que não será seu problema), o pensamento de fazer a documentação é extremamente doloroso.

Muitas das outras respostas encobrem o ponto de que existem pelo menos dois tipos de documentação: um definido para outros desenvolvedores e outro diferente para os usuários finais. Dependendo do seu ambiente, você também pode precisar de documentação adicional para administradores de sistema, instaladores e equipe de suporte técnico. Cada público-alvo tem diferentes necessidades e níveis de entendimento.

Considere o desenvolvedor típico (estéreo): ele é um codificador por opção. Ele escolheu uma carreira fora dos olhos do público e passa longas horas atrás de um teclado se comunicando principalmente consigo mesmo. O processo de documentação é uma forma de comunicação e o conjunto de habilidades necessárias para produzir uma boa documentação é antitético às habilidades necessárias para produzir um bom código.

Um bom escritor de documentação pode se comunicar em vários idiomas: o idioma dos usuários, o idioma do gerenciamento, o idioma da equipe de suporte, o idioma dos desenvolvedores. É tarefa de um redator de documentação entender o que um codificador se comunica e traduzir isso em um formato que todos os outros grupos possam entender.

Quando você espera que os codificadores desenvolvam a habilidade necessária para se tornarem bons comunicadores (escritos ou não), a quantidade de tempo gasto na aprimoramento do conjunto de habilidades primárias (codificação!) Diminui. Quanto mais longe ele fica de sua zona de conforto (codificando e se comunicando com outros codificadores), mais tempo e energia serão necessários para executar bem a tarefa. Você pode razoavelmente esperar que um programador profissional deseje se concentrar principalmente em suas principais competências, às custas de todas as outras.

Por esse motivo, é melhor deixar a documentação (com exceção dos comentários do código embutido) para comunicadores, não para codificadores.

A leitura do código mostra como ele funciona. Não pode explicar o porquê : você precisa de comentários.

A leitura do código mostra o nome de um método e os tipos dos parâmetros. Não pode explicar a semântica ou a intenção exata do autor: você precisa de comentários.

Os comentários não substituem a leitura do código, eles adicionam a ele.

A documentação não é executada como o código. Como resultado, muitas vezes não há loops de feedback eficazes para verificar se a documentação está no lugar e está completa. Esse é o mesmo motivo pelo qual os comentários do código tendem a apodrecer.

Donald Knuth promoveu a programação alfabetizada como uma maneira de melhorar a qualidade do software, escrevendo efetivamente a documentação com o código. Eu já vi alguns projetos que usaram essa abordagem com bastante eficiência.

Pessoalmente, tento manter a tendência moderna de manter a API pública do seu código o mais legível possível e usar testes de unidade para documentar o uso de outros desenvolvedores. Acho que isso faz parte da idéia maior de ter sua API de uma forma que possa ser explorada e descoberta. Penso que esta abordagem faz parte do que o HATEOAS tenta alcançar com os serviços da web.

Um ponto menor, mas que parece ser importante para alguns desenvolvedores que escrevem escandalosamente pouca documentação: eles não podem digitar. Se você tem alguma aproximação do sistema de 10 dedos, costuma escrever mais documentação apenas porque é fácil. Mas se você está preso em caçar e bicar, está perdido. Se eu fosse responsável pela contratação, isso seria algo que eu verificaria.

As pessoas que não gostam de ler a documentação não gostam de escrever a documentação. Muitos programadores farão todo o possível para evitar a leitura completa de um documento.

Não se concentre na escrita, concentre-se na leitura. Quando os programadores leem a documentação e assimilam as coisas, eles verão o valor e estarão muito mais inclinados a escrever alguns.

Quando iniciei meu trabalho atual e assumi um projeto de hardware + software das pessoas que anteriormente trabalhavam nele, recebi um documento com cerca de cem páginas por página descrevendo o sistema. Deve ter levado dias para produzir. Eu olhei para ele talvez duas vezes. Apesar da enorme quantidade de informações existentes, raramente respondia às perguntas reais que eu tinha sobre o sistema e, mesmo quando o fazia, era mais rápido olhar o código.

Depois de experiências suficientes como essa, você começa a pensar: por que se preocupar? Por que gastar seu tempo respondendo perguntas que as pessoas nunca fizeram? Você começa a perceber como é realmente difícil prever quais informações as pessoas buscarão na documentação; está inevitavelmente cheio de fatos que se revelam inúteis, pouco claros ou óbvios e sem respostas para as perguntas mais prementes. Lembre-se, produzir documentação útil é um esforço para prever o comportamento humano. Assim como é improvável que um projeto de interface com o usuário seja bem-sucedido antes de passar por várias iterações de teste e depuração, é ingênuo pensar que é possível escrever documentação útil com base apenas nas expectativas de como as pessoas interpretarão o sistema e o que papel que a documentação e seu idioma desempenharão nessa interpretação.

Costumo pensar que a maior parte da pressão para escrever documentação decorre do fato de ser uma tarefa desagradável e as pessoas gostam de se culpar em tarefas desagradáveis ​​("Você não comeu o seu filboide!").

CONTUDO

Não creio que a documentação seja, em todos os aspectos, inútil. Eu acho que é impossível principalmente quando as pessoas veem a documentação como esse fardo extra que deve ser cumprido antes que um trabalho seja concluído, como um último pedaço de trabalho de limpeza a ser feito rapidamente e como uma caixa a ser verificada. Documentação é algo que você deve trabalhar nos aspectos do seu dia que você sempre faz de qualquer maneira. Eu acho que o email é uma maneira particularmente boa de fazer documentação. Ao adicionar um novo recurso, escreva para algumas pessoas um e-mail rápido dizendo o que é. Ao desenhar um novo esquema, gere um PDF e envie-o para qualquer pessoa que esteja interessada. As vantagens do email são:

1. As pessoas geralmente verificam o email, enquanto ninguém vasculha uma pasta chamada "doc".

2. O e-mail existe no contexto, cercado por outros e-mails que discutem o recurso e os recursos relacionados e qualquer outra coisa que estava acontecendo no momento.

3. O email é curto e focado e tem uma linha de assunto.

4. O e-mail permite que as pessoas que desejam fazer perguntas imediatamente,

5. O email é altamente pesquisável, porque as pessoas o usam para tudo e os clientes de email avançaram bastante ao longo dos anos.

6. Se estiver em um email, pelo menos uma outra pessoa sabe onde encontrá-lo.

Em teoria, parece que os comentários no código também devem ser "aspectos do seu dia que você sempre faz", mas, para ser sincero, nunca leio comentários no código. Não sei por que, mas eles não são muito úteis, talvez porque haja uma falta de contexto, o que o email resolve.