Degradação da documentação - como lidar com isso?

Importante : não temos nenhum problema com a documentação do código fonte . Isso pertence à auditoria regular de código e é mantido atualizado. Nosso problema é com a documentação dos desenvolvedores (ou "externos", se você preferir), pequenas dicas de programadores para programadores que tendem a ser escritas uma vez, geralmente deixadas para trás.

Usamos um sistema semelhante ao wiki para produzir documentação para programadores - artigos escritos por programadores para programadores descrevendo um pouco mais detalhadamente como funciona um determinado código. Essas páginas wiki geralmente incluem:

• motivações por trás das decisões de design para partes da API (por exemplo; fizemos essa coisa feia porque essa biblioteca de terceiros em particular quer que as coisas sejam feitas dessa maneira, porque essa outra biblioteca ..., porque ...)
• explicação de como lidamos com tarefas comuns específicas (por exemplo; exibição de pop-up trivial, que precisa fazer referência a estilos de aplicativos apropriados, registrar-se no componente do registro e implementar alguma interface para ser "varrida" automaticamente por outro componente)
• boas práticas (subjetivas, na verdade, escrevemos essas coisas)
• configuração do ambiente, ferramentas necessárias e sua configuração

Em geral, principalmente coisas relacionadas à escrita de código que não se encaixam na documentação regular do código devido ao tamanho e natureza do artigo / artigo do blog.

O problema

Quanto à introdução desse sistema, parecia uma boa idéia há alguns meses, hoje em dia sinto que está causando mais problemas do que resolve. Por exemplo:

• as pessoas fazem escrever artigos ... mas uma vez que o código mudou, atualização wiki raramente segue
• muitos artigos de rascunho , escritos por alguém com pressa e saídos assim
• mesmo que a solicitação de artigo geralmente venha do líder do projeto, quase nunca é verificada a correção / composição - o que às vezes resulta em baixa qualidade

A degradação usual. Código alterado, o wiki permanece o mesmo. Da próxima vez que alguém procurar informações, o que ele normalmente encontra é um monte de coisas desatualizadas e de baixa qualidade - e está se perguntando o que está acontecendo, se as coisas que ele encontrou são precisas ou (ainda pior) quais são as partes. E o que deveria ajudar acaba fazendo o oposto.

No momento, parece que as pessoas estão cientes do problema, incluindo o líder do projeto, mas aparentemente ninguém parece se incomodar em fazer algo com ele (ou tem coisas mais interessantes para fazer).

Meu pensamento inicial foi jogar tudo no esquecimento (depois que fui mordido por "dicas" desatualizadas algumas vezes seguidas), mas suponho que isso possa ser extremo demais. Algumas informações são dignas de nota e, às vezes, são de boa leitura, mas o problema ainda é o mesmo: como você lida com sua "atualização" ? Ele está vinculado ao código-fonte de alguma forma (portanto, quando a versão atualizada do arquivo é registrada, o autor do artigo é notificado de que pode precisar revisar o código / artigo)? A pessoa designada "vigia" o básico diariamente? Faz limpezas regulares?

Parece que você está documentando curiosidades demais no wiki.

Documente blocos de código e métodos no código . Tente fazer seu código se auto-documentar, para que você não precise fazer muitos comentários. Escrever testes de unidade também pode ajudar.

Documente as decisões e a arquitetura do projeto com maior granularidade no wiki, para que o wiki não precise mudar com frequência ou precise de muito trabalho para mudar. Se muitas pessoas em sua equipe já conhecem a arquitetura e a equipe não está crescendo rapidamente, talvez não exista uma forte justificativa para documentá-las, pessoalmente, geralmente é a melhor transferência de conhecimento.

Reescreva ou exclua as informações desatualizadas imediatamente , como código morto, quanto mais tempo permanecer, mais difícil se tornará a localização e mais acumulará. Se você não tiver tempo, basta excluí-lo e marcar o artigo como necessitando de retrabalho, o torna mais lento e é armazenado no controle de versão de qualquer maneira.

Documente os procedimentos automatizando-os em um script ou arquivo de instalação. Caso contrário, mantenha-os no wiki, mas sempre que alguém usar um procedimento do wiki, peça para tentar melhorar o artigo ou automatizar partes do processo.

Os artigos de blog pertencem a blogs . Se as pessoas querem compartilhar suas opiniões e conselhos pessoais, crie um blog da empresa para isso. Eles provavelmente não querem que seus artigos sejam modificados e ninguém os modificará de qualquer maneira, portanto, não os deixe desorganizados no wiki.

A documentação deve ser tratada como uma entrega e, portanto, sujeita às regras de rastreabilidade e aceitação, bem como a quantidade de tempo apropriada a ser desenvolvida.

Não é incomum ver as pessoas "esperando" que a documentação do software seja um dado, quando não é.

Radical, mas eficaz. Se alguém escreveu um novo módulo, mas não o documentou - reabra a tarefa no rastreador de problemas e, se necessário, impeça o envio de todo o código-fonte não documentado. Se você permitir que os desenvolvedores tratem a documentação do código-fonte como necessário, você acabará com fragmentos de documentação fragmentados e desatualizados.

No meu projeto recente, tendemos a rastrear pelo menos todas as bibliotecas de terceiros necessárias. Se alguém apresentar uma nova biblioteca, mas ela não estiver documentada - reverteremos a solução até que a documentação seja apresentada. Sem uma abordagem tão radical, haveria caos. Por exemplo, um desenvolvedor inexperiente pode usar uma biblioteca cuja licença está em conflito com a licença do nosso software.

Se algo está mudando rapidamente, não deve ser mantido fora do código.

motivações por trás das decisões de design para partes da API

Isso é especialmente importante para manter-se próximo ao código. Como no mesmo arquivo de origem. Dessa forma, será um pouco mais difícil ignorar sempre que alguém tocar o arquivo e solicitar menos envios ao TheDailyWTF por pessoas que não sabem que a documentação externa existe.

A degradação usual. Código alterado, o wiki permanece o mesmo.

É aqui que a "documentação executável" - testes de unidade - se torna muito útil. Se o código for alterado e os testes não forem alterados, a compilação será interrompida. Obviamente, escrever testes como documentação requer alguma habilidade. Mas o mesmo acontece com a documentação externa (boa).

Uma boa maneira de lidar com o problema é torná-lo parte do processo. Se você tiver um rastreamento de código para / referenciar as páginas relevantes no wiki, um desenvolvedor poderá descobrir facilmente o que precisa ser atualizado. Além disso, responsabilize os revisores em uma revisão de código por garantir que o wiki esteja atualizado (com relação à atualização).

Outra maneira de adicioná-lo como parte do processo - como você está usando um modelo ágil, parte do processo de planejamento para iterações, pode ser atualizar as alterações planejadas no wiki. O wiki então serve como um recurso "é assim que as coisas devem funcionar".

Se você estiver usando uma linguagem .net, consulte ( Sandcastle ), que pega a documentação XML (/// em C #) e a converte no formato de ajuda do MSDN.

O formato inclui descrição, comentários e pode incluir exemplos de código, além de alguns outros recursos. Você pode produzir nos formatos .CHM, .HsX, .MSCH e HTML / ASP.NET. O projeto real é adicionado à sua solução e criado no servidor de compilação. Fizemos isso e implantamos em um site a cada lançamento, e os consumidores adoram porque a documentação é relevante para o lançamento e é atualizada constantemente.

Você também pode especificar o que incluir na documentação. Atualmente, temos dois projetos: um para consumidores externos, que inclui apenas os contratos e itens apropriados (classes, enumerações, etc.) e outro para desenvolvedores internos, que inclui tudo na API, incluindo itens sinalizados privados e internos.

Essa se tornou a única documentação que usamos, pois motivações e peculiaridades sobre o uso da API podem ser incluídas na seção Comentários da documentação. O processo funciona bem onde eu trabalho.

Eu focaria em duas áreas: 1) O código. 2) Notas e documentos sem código.

1) O código

Tente fazer a auto-documentação. No passado, descobri que isso era frequentemente recomendado, mas raramente explicado bem, então ...

Em vez deste tipo de pseudo-código:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Faça um código mais parecido com isto:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Use o controle de origem para rastrear as informações 'quem fez o quê quando'.

2) O não código

Use um formato wiki e markdown para manter essas informações. Faça parte do trabalho. Divulgue, publique e publique no blog. Configure uma reunião semanal ou mensal padrão para revisar coisas antigas e novas. Faça um mantra: quando alguém pergunta sobre algo, a resposta é dada ... junto com o pensamento "isso deve estar no wiki pela próxima vez que alguém perguntar?"