O que há com a aversão à documentação na indústria?

Eu não acho que seja útil especular sobre as motivações de pessoas que não estão adotando algo que você acha que é uma boa prática ou que estão continuando a fazer algo que você considera uma prática ruim. Neste negócio, as pessoas que se enquadram em uma ou ambas as categorias serão muito mais numerosas do que aquelas com as quais você vai encarar, então pare de enlouquecer.

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

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

Pode não ser realista esperar que todos em sua equipe direcionem seus esforços para as coisas que você considera um problema. Isso é especialmente verdadeiro se você for um novato em relação à equipe. Eu me atreveria a adivinhar que você é, porque se você fosse um membro fundador da equipe, parece muito provável que você já tenha resolvido esse problema desde o início.

Considere, em vez disso, trabalhar com o objetivo de escrever uma boa documentação e convencer 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 o aponto para o Projeto. Uma página wiki.

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

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

2. Prove o valor da sua documentação

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

For future reference, the wiki page of this project has information about the branch of the core code that was created for ongoing support of release 2.1, so in future we can avoid having to do a full regression test if people who are maintaining released versions check the wiki before checking out the code.

ou

I am so glad I wrote down the steps for doing Task T. I don't really care if no one else ever uses it--it's already saved me more time than what I spent writing it.

3. Obtenha o gerenciamento on board

Após alguns incidentes em que a documentação está comprovadamente economizando tempo / dinheiro, você provavelmente notará um "degelo" distinto em relação à documentação. Este é o momento de pressionar o ponto, começando a incluir o tempo de documentação em suas estimativas (embora, honestamente, eu normalmente atualize / crie documentos enquanto processos longos estão sendo executados, 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 (o que pode ser bem).

4. Incentivar a documentação quando você a vê

Talvez parte do motivo pelo qual as pessoas não escrevem documentos com a frequência necessária é que ninguém as lê. Então, quando você vê algo de que gosta, certifique-se de pelo menos mencionar que estava feliz por estar disponível.

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

Thank you for documenting the workaround for bug B in Framework G. I didn't know about that, and I don't think I could have understood what you were doing without that in there.

Se você tem alguém na equipe que realmente está entusiasmado com a documentação, não faz mal cultivar essa pessoa indo almoçar ou tomar café e certificando-se de oferecer uma pequena validação para neutralizar o desânimo eles podem perceber que o resto da equipe não valoriza muito a documentação.

Além disso, não é problema seu, a menos que você esteja em uma posição de liderança ou gerenciamento. Você pode levar um cavalo à água, mas não pode 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 o cocho.

Existem dois fatores principais na minha experiência:

Prazos

A maioria das empresas é tão impulsionada pela data que o QA, a dívida de tecnologia e o design atual são cortados apenas para que o gerente de projetos não pareça ruim ou atinja algum prazo de cliente absurdamente prometido. Nesse ambiente em que até mesmo a qualidade funcional é cortada, um investimento a longo prazo, como a documentação, tem poucas chances.

Alterar

Uma prática recomendada relativamente nova para desenvolvedores é reduzir a ênfase nos comentários. A ideia é que manter as informações em dois lugares (o código [incluindo testes] e os comentários em torno do código) leva a muita sobrecarga para mantê-los sincronizados 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, não vou mais olhar para os comentários. O 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 uso generalizado de refatoração, a organização do código mudará substancialmente. Por que gastar o tempo documentando todas essas coisas que estão prestes a mudar? Código e testes devem fazer um bom trabalho fazendo isso.

Há vários fatores em jogo aqui:

1. O código bem escrito é sua própria documentação. Todas as outras coisas sendo 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 a documentação quando alterar esse código.

2. Escrever documentação é sem dúvida uma habilidade diferente do que 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 estão escrevendo documentação.

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

4. A boa documentação é demorada e difícil de fazer bem. Todas as outras coisas sendo iguais, pode haver mais valor para escrever código novo 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 isso precisa ser alterado.

6. Ninguém lê a documentação, então por que se incomodar?

Elefante na sala: os programadores não são (necessariamente) escritores. Tampouco são necessariamente passíveis de consubstanciar suas implementações para escritores técnicos. Segundo elefante na sala: Os redatores técnicos geralmente não são capazes de 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 devida documentação. O código se torna menos valioso inversamente proporcionalmente à sua verificação [sic]. Resolvido, o gerenciamento contrata o Engenheiro de Software que pode ler os detalhes de código e coaxial dos desenvolvedores, paga-o a uma taxa de desenvolvedor e obriga-o a 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 QA, você tem um departamento de documentação interna.

O código se tornará mais valioso, já que você pode licenciá-lo para uma terceira parte (porque ele pode entendê-lo), o código pode ser mais facilmente auditado e melhorado / re-fatorado, você terá melhor reutilização de código Você pode fatorar facilmente versões mais leves de seu software, e você será capaz de introduzir novos desenvolvedores mais facilmente no projeto, seus engenheiros de suporte vão adorar trabalhar para você.

Isso nunca acontecerá.

More importantly, how do I convince them that writing docs will save us time and frustration in the future?

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 possuem, etc. Basicamente, tudo que é usado pesado e diariamente. Informações erradas serão encontradas rapidamente e serão corrigidas. Precisa ser fácil e fácil de editar (por exemplo, Wiki on-line).

Documentação inútil

Documentação que muda com frequência, 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 uma palavra doc escondidos em algum lugar no SVN, atualizados há 3 anos. Esta documentação vai 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.

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 grande sucesso com isso em meu último projeto ao introduzir um Wiki onde poderíamos escrever todas as informações de que precisamos com frequência.

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

Documentação do produto / release

Isto é tudo o que sai com o seu produto 'acabado'. Isto é mais do que apenas manuais, isto é, READMEs, Change Logs, HOW-TOs e afins. Em teoria, você pode se safar se não as escreve, mas acaba com um produto que as pessoas não querem usar, ou um ônus de suporte que é desnecessariamente caro.

Documentação da API

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

Comentários de código

A opinião da indústria sobre os comentários parece estar em fluxo, no momento. Quando comecei a codificar profissionalmente, os comentários eram uma sine qua non quando se tratava de escrever código. Agora, a moda é escrever código tão claro que os comentários são desnecessários. Eu diria que isso é, em parte, devido ao fato de que muitas linguagens modernas são escritas em um nível muito mais alto e é 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 de código, ou alguns detalhes sobre por que um determinado algoritmo foi escolhido sobre um mais óbvio (para evitar excesso de zelo refatorando os demônios do código de 'fixação' que não precisa ser corrigido de fato.

Infelizmente, há muito egoísmo, racionalização e auto-ilusão envolvidos nas decisões dos programadores para 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 para escrever (ou não escrever) documentação, em qualquer nível, são aquelas que devem ser feitas no nível da equipe. Para os níveis mais altos de abstração, pode fazer mais sentido ter alguém, além de desenvolvedores, para fazer isso. Quanto à documentação no nível dos comentários, chegar a um acordo sobre o propósito e a intenção dos comentários deve ser acordado em conjunto, especialmente em equipes de habilidades e experiência mistas. Não adianta fazer com que os desenvolvedores seniores escrevam códigos que os desenvolvedores juniores não podem 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 Manifesto Ágil declara "Software operacional sobre documentação abrangente" e nem todo mundo lê para alcançar "Ou seja, enquanto houver valor nos itens à direita, valorize mais os itens à esquerda. "

2. Infelizmente, é comum o link e a documentação não funciona com esse modelo. sincronizar).

3. A indústria de desenvolvimento de software não é bem regulada. Não há exigência legal para escrever documentação.

4. O código de autodocumentaçã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 que foi pior do que inútil. Eles têm a idéia de que não apenas documentar os problemas de seu gerente (o mesmo cara que continua cortando a parte de controle de qualidade do cronograma), mas também não ajudará ninguém, inclusive eles.

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

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

Considere o desenvolvedor (estéreo) típico: 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 que se comunica 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: a linguagem dos usuários, a linguagem de gerenciamento, a linguagem da equipe de suporte, a linguagem dos desenvolvedores. É o trabalho de um escritor de documentação entender o que um codificador comunica e traduzi-lo em uma forma que todos os outros grupos possam entender.

Quando você espera que os programadores desenvolvam a habilidade necessária para se tornarem bons comunicadores (escritos ou não), a quantidade de tempo gasto aprimorando o conjunto de habilidades primárias (codificação!) é diminuída. Quanto mais ele se distancia 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 todos os outros.

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

A leitura do código mostra a você como funciona. Não é possível explicar por que : 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 efetivos para verificar se a documentação está pronta e completa. Essa é a mesma razão pela qual os comentários de código tendem a apodrecer.

Donald Knuth promoveu a Programação Literária como uma maneira de melhorar a qualidade do software, efetivamente escrevendo a documentação com o código. Eu 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 ideia maior de que sua API seja de uma forma que possa ser explorada e descoberta. Acho que essa abordagem é parte do que HATEOAS tenta alcançar com os serviços da Web.

Um ponto menor, mas que parece ser importante para alguns desenvolvedores que escrevem pouca documentação: eles não podem digitar. Se você tem alguma aproximação do sistema de 10 dedos, você tende a escrever mais documentação só porque é fácil. Mas se você está preso com a caça e bicando você está perdido. Se eu fosse responsável por contratar isso, seria algo que eu verificaria.

As pessoas que não gostam de ler documentação não gostam de escrever documentação. Muitos programadores farão tudo o que puderem 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 uma centena de documentos em Word descrevendo o sistema. Deve ter levado dias para produzir. Eu olhei para isto talvez duas vezes. Apesar das enormes quantidades de informação, raramente respondia às perguntas 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 incomodar? Por que gastar seu tempo respondendo perguntas que as pessoas nunca perguntaram? Você começa a perceber como é realmente difícil prever quais informações as pessoas buscarão na documentação; está inevitavelmente preenchido com fatos que se revelam inúteis, obscuros ou óbvios, sem as respostas às perguntas mais prementes. Lembre-se, produzir documentação útil é um esforço para prever o comportamento humano. Assim como um design de interface de usuário provavelmente não terá êxito antes de passar por várias iterações de teste e depuração, é ingênuo pensar que é possível escrever uma documentação útil baseada apenas nas expectativas de como as pessoas interpretarão o sistema e papel que a documentação e sua linguagem desempenharão nessa interpretação.

NO ENTANTO

Eu não acho que a documentação seja, de todas as formas, sem esperança. Eu acho que é desesperador principalmente quando as pessoas olham para a documentação como esse fardo extra que deve ser preenchido antes que um trabalho seja concluído, como um último trabalho de limpeza a ser apressado, 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. Quando você adiciona um novo recurso, escreva para algumas pessoas um e-mail rápido dizendo o que é. Quando desenhar um novo esquema, gere um PDF e envie-o para qualquer pessoa que possa estar interessada. As vantagens do email são:

1. As pessoas geralmente verificam o e-mail, enquanto ninguém percorre 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 e-mail é curto e focado e tem uma linha de assunto.

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

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

6. Se estiver em um e-mail, pelo menos uma outra pessoa saberá 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 de qualquer maneira", mas, para ser honesto, nunca li comentários no código. Não sei por que, mas eles não são muito úteis, talvez porque haja falta de contexto, que o email resolve.