Determinando a quantidade certa de documentação

Onde atualmente trabalho, a abordagem geral é -

evitar a documentação o máximo possível

Documente apenas se uma equipe diferente precisará

apenas para esclarecimento, não me refiro à documentação do código - é o que fazemos, quero dizer toda a documentação que envolve o processo de design - se for esquemas UML ou DB, diagramas de classes e documentos do Word com especificações e afins.

Vou listar o motivo do meu chefe para não documentar:

1. é demorado - concentre-se na implementação
2. se a alteração do projeto - a documentação deve mudar, o dobro de problemas
3. no final, você recebe centenas de páginas que ninguém quer ler, e ninguém realmente edita; assim, com o tempo, ela ficará desatualizada
4. É uma dor - ninguém realmente quer fazê-lo

Agora percebo que trabalhamos mais rápido, mas também me lembro da hora de chegar aqui e mergulhar direto em algum código antigo, sem entender nada.

Na verdade, ainda não recebo a maior parte desse código antigo e, às vezes, quando entro, vejo muitos patches de diferentes desenvolvedores tentando fazer pequenos ajustes.

Realmente acho que a falta de documentação promove esse tipo de correção e a falta de entendimento do sistema em um sentido amplo.

minha pergunta é:

Como podemos equilibrar a documentação para promover o conhecimento contínuo da equipe e ainda assim sermos rápidos e eficientes?

Eu encontrei QUALQUER documentação é melhor do que nenhuma documentação. A quantia apropriada geralmente é determinada pela quantidade de tempo que temos para fazê-lo ou por quanto odiamos suporte a telefonemas e e-mails.

Parece que os membros atuais de sua equipe têm expectativas irreais de suas memórias, ou têm vergonha de suas habilidades de escrita e não estão dispostos a praticar.

Percebo que sou uma minoria (especialista em inglês que ingressou em engenharia de software na pós-graduação) aqui, pois não encontro documentação como tarefa. É uma ferramenta profissional valiosa. Talvez eu não ache a escrita tão difícil quanto alguns de meus colegas de trabalho, mas isso ocorre principalmente porque tenho mais prática. Não considero um projeto concluído, a menos que tenha documentação, e geralmente o escrevo por razões puramente egoístas: para que eu possa dar às pessoas algo para ler em vez de atender telefonemas e e-mails, ou para lembrar do que estávamos conversando pela última vez mês ou mais, posso me referir a como fiz algo se precisar apoiá-lo no meio da noite.

A melhor maneira de abordar a documentação é escrevê-lo COMO VOCÊ VAI, exatamente como escrever código de teste. É incrível como alguns modelos pré-escritos (com cabeçalhos, stubs de código etc.) podem tornar a documentação mais fácil e rápida. Dessa forma, você pode capturar as mudanças à medida que elas acontecem e ter menos espaço para cobrir com o tempo. Você é mais eficiente dessa maneira, pois pode consultar a documentação conforme necessário e alterá-la ao longo do caminho. Fazer isso em um wiki, por exemplo, facilita as atualizações, e você pode evitar problemas de versão do documento se o mais recente e o maior estiverem sempre on-line no mesmo lugar, e você pode simplesmente enviar links para as pessoas que precisam lê-lo.

Se você gastar um pouco de tempo documentando, TODOS trabalharão mais rápido, especialmente quando alguém novo ingressar na equipe, pois eles não terão que gastar todo esse tempo tentando descobrir tudo. Descobrir as coisas é uma parte divertida de nossos trabalhos, mas não é divertido quando você precisa fazer isso com pressa para corrigir a produção. Todos pouparíamos muito tempo se escrevêssemos mais algumas notas.

Sua equipe tem os mesmos problemas ao testar ou escrever código de teste? Caso contrário, será mais fácil vender.

Sua documentação é útil de várias maneiras:
1) Para você, agora e para seus colegas de trabalho, enquanto trabalha no projeto.

2) Para seus clientes. A documentação (incluindo diagramas) que você pode mostrar aos usuários facilita as discussões nas reuniões, especialmente se você estiver discutindo sistemas complicados. Mesmo se a documentação estiver incompleta, é um ponto de partida.

3) Para as pessoas que herdarão seu trabalho (que pode até ser você, em três anos). Muitos dos meus colegas de trabalho mais jovens pensam que vão se lembrar das coisas para sempre. Sei que não vou me lembrar dessa semana se não anotá-la. Ter documentação evita que você gaste meio dia para se lembrar de como você estruturou algo e precise descobrir tudo de novo.

4) Para você e outras pessoas, se a situação se tornar política ou contenciosa. Como alguém que toma notas nas reuniões, para me manter acordado e combater o tédio, muitas vezes fui o único com a versão escrita de uma decisão. A pessoa que a escreveu vence a disputa. Lembre-se disso da próxima vez que alguém disser "Lembre-se daquela reunião que tivemos no inverno passado na sala de conferências 4, quando estávamos examinando X? Fred estava lá e quem é esse cara da Contabilidade?"

Nos meus últimos empregadores, tivemos um wiki de "desenvolvimento". Pedaços significativos de funcionalidade (novo feed de importação / exportação, como o subsistema de segurança funciona, onde o sistema armazena documentos carregados etc.) são todos documentados lá. Geralmente, é um item obrigatório a ser concluído antes da etapa de revisão do código. Geralmente, há um pouco de resistência a isso no começo, mas quando alguém precisa procurar um pouco de informação e ela está lá, você tem outro convertido.

O bom de tê-lo em um formato wiki é que você está muito menos inclinado a fazer toda a bonita formatação do Word e tal e apenas escreve as informações reais que precisa salvar. A maioria dos pacotes wiki (se não todos) permitirá o upload de documentos ou imagens (como diagramas do Visio UML ou wireframes da interface do usuário), para que você possa ter peças visuais também.

Como a maioria das coisas, acho que você deve tentar fazer a quantidade mínima que possa funcionar. Isso não é a mesma coisa que nenhuma.

Você não pode deixar de alocar tempo para escrever a documentação adequada. Equilibre-o da maneira que desejar, dependendo de quanto trabalho você tiver, mas deixe de 15 a 20% do seu tempo para documentar o que você fez. Todo mundo na equipe precisa estar presente, incluindo o seu gerente, caso contrário, você estará documentando apenas para o benefício de outras pessoas e não receberá nada em troca. A documentação deve ser parte integrante do seu processo de desenvolvimento.

A documentação deve dizer POR QUE você fez alguma coisa enquanto deixa a parte COMO no código real e a parte QUASE nos testes de unidade. Qualquer coisa mais é uma dor. Isso geralmente é bom o suficiente para pessoas inteligentes que querem apenas um ponto de partida.

Além disso, não se esqueça de manter uma arquitetura geral de alto nível de cada grande componente de sua base de código. Facilita a introdução de novos membros da equipe.

Finalmente, sempre que você adicionar uma correção maluca, conecte-se ao seu banco de dados de bugs a partir de um comentário - muito útil.

Seu chefe está certo, não imprima nenhuma documentação UML que ninguém leia. O que fazemos em nossa equipe é navegar ao vivo no modelo usando visualizações de diagrama de classes. O princípio é sempre atualizar o MOF, o modelo UML a partir do código e permitir que o diagrama de classes seja apenas um visualizador do modelo, mas não o próprio modelo.

Funciona muito bem porque toda a complexidade é feita no backoffice no nível do modelo. Posso refatorar meu projeto, escrever java doc ou escrever documentação uml no modelo. É um tipo de clique e pronto. Ao clicar, você obtém a documentação ao vivo. Se algo não estiver claro, abro o diagrama de classes e começo a brincar com ele. Excluir dos classificadores do diagrama, adicionar novos classificadores, aumentar e diminuir o zoom, mostrar associação, excluir associação, etc.

É realmente importante abrir o diagrama de um pacote e poder ler diretamente no diagrama de classes um comentário sobre o que essa classe deveria ser. O que esse método deve fazer e qual é o fluxo, etc.

A UML é excelente, realmente útil, mas devemos parar de usar o Desenvolvimento Orientado a Modelo para dar mais flexibilidade e mais iteração nos estágios de modelagem / desenvolvimento. O diagrama de classes é atualizado ao vivo a partir do código e a documentação é sempre precisa e disponível apenas com um clique. Não mencionarei uma ferramenta, mas se você usa Java e Eclipse, é fácil encontrar qual ferramenta eu uso :-)