Como posso documentar o trabalho anterior de outra pessoa? [fechadas]

Estamos em uma situação ruim de ter muito pouca documentação sobre personalização que nossos funcionários anteriores fizeram em um sistema crítico de negócios. Muitas alterações foram feitas no Crystal Reports, entidades de banco de dados e arquivos de configuração / programação proprietários para o nosso software ERP.

A documentação atual geralmente lê algo como isto:

Este programa é executado antes do faturamento. Erros conhecidos: nenhum.

Execute este programa após instalar o software X.

Os seguintes campos foram alterados neste relatório: (sem explicação de como ou por que)

Nossa loja de TI é pequena e, no caso do software ERP, a maior parte do trabalho foi concentrada em uma pessoa (agora sou eu), então ninguém mais aqui sabe o que fizemos. O departamento de TI e contabilidade conhece partes (ocasionalmente bastante úteis), mas não é suficiente.

Outro problema é que nosso departamento de contabilidade parece achar que estamos bem documentados. É verdade que mantivemos muitos registros do que deu errado , mas muito pouco explica o que foi feito (se alguma coisa) para corrigir esses problemas. Temos centenas de artigos explicando erros, mas os documentos que explicam as alterações (como mostrado acima) são quase inúteis.

Como posso documentar mudanças passadas quando não sei o que foi feito? Posso começar documentando o que mudamos: Arquivos, tabelas de banco de dados, etc., que precisamos ter para o sistema funcionar. Eu também posso documentar o que fazemos ; Quando os relatórios são executados, por que as pessoas foram instruídas a usar o X report / program. Mas quando uma dessas coisas personalizadas tem um problema, estou sempre de volta à estaca zero.

Como posso documentar proativamente essas coisas para mim e para os outros?

Eu acho que este é um exercício fútil. Se funcionar, funciona, se não funcionar, você precisa corrigi-lo.

A melhor maneira de documentar coisas antigas é enquanto você trabalha nela, documenta o que está fazendo e explica a lógica de negócios (que eu assumo que não foi documentada). Isso será uma grande ajuda para qualquer novo desenvolvedor.

Falando em documentar códigos / coisas antigos, alguém tinha que possuí-lo. Vamos supor que este seja seu gerente atual. Ele / ela pode não ter conhecimento técnico completo, mas saberá quais alterações foram feitas. Nesse caso, não é seu trabalho. Pode ser que o gerente possa escrever algo sobre o que as alterações foram feitas. Isso seria útil para manter a história. Se surgirem problemas como esse, você poderá cavar nessas áreas, isso pode ser muito útil para você. Mas entrar no código e documentar as alterações é IMO bastante inútil e provavelmente impossível.

Abandone seu esforço para documentar alterações .

Em vez disso, comece a documentar o que atualmente funciona e como . Mantenha essa documentação atualizada e atualizada à medida que fizer alterações no futuro.

Você tem controle de origem?

Você pode descobrir o que mudou a partir disso?

Nesse caso, você poderá mapear isso para alterações nos negócios, sejam novos recursos ou correções de erros.

É possível ressuscitar uma caixa de correio antiga de desenvolvedores? (não tenho certeza se isso é viável com questões de privacidade ou não). Pode haver muita informação a ser obtida arrastando-se por lá.

Primeiras coisas primeiro. Onde você está armazenando sua documentação? Se você ainda não o fez, configure um wiki. Eu mesmo prefiro o dokuwiki , e há até um vm pré - construído , se você estiver inclinado.

Isso fornece alguns recursos importantes:

• Os documentos podem ser acessados ​​em qualquer lugar da LAN da empresa (instalando em um novo computador ...)
• Todos os documentos estão em um só lugar
• Todos os documentos são pesquisáveis
• Você pode colaborar (novo colega, usuários do software)

Agora, se sua documentação estiver em papel, desejo-lhe o melhor. Se você possui documentos do word, crie um script de importação .

Finalmente, basta usar as coisas . Sempre que você precisar instalar algo, coloque notas no wiki. Se você acertar um exemplo, coloque-o no wiki. É aqui que a colaboração pode brilhar, já que você leva outras pessoas a fazer o trabalho por você.

Passando para uma documentação mais específica, se você precisar trabalhar com a fonte de vários projetos, verifique se possui um ambiente de desenvolvimento adequado ! Para uma lista de verificação, você deve ter:

• Controle de versão ( git , mercurial , fóssil )
• Rastreamento de bugs ( trac , mantis , redmine , fossil )
• Sistema de construção ( autotools , scons , buildbot )
• Controle do projeto ( eclipse , estrutura de diretórios especificada, plugin do editor )
• Documentação de origem (README, TODO, INSTALL, Source comments)

Finalmente, como a documentação pode ser entediante, torne-o um jogo. Dê a si mesmo "pontos" para cada item da sua lista de verificação, verificando periodicamente sua "pontuação". É uma boa maneira de ver o que você realizou e quão bem. Ele também mapeia para onde você precisa ir a seguir.

Veja isso como uma oportunidade de aprender muitas coisas sobre como configurar um ambiente de desenvolvimento adequado e não tenha medo de tentar as coisas e seguir em frente. Encontre algo que você gosta e migre o ambiente para que tudo fique melhor . Aborde isso como um projeto em que você deseja criar a melhor solução.

Editar:

Conforme o comentário da plataforma abaixo, outra coisa útil a se fazer é criar diagramas do código fonte. O Freecode tem coisas , e este artigo lista alguns dos idiomas populares.

O melhor que você pode fazer é documentar tudo o que sabe e pedir à empresa para documentar tudo o que os outros também sabem. Sugiro centralizar a documentação em um wiki ou algo semelhante para que todos tenham acesso à documentação mais atualizada.

Você não pode documentar algo que não conhece; portanto, tenta aprender e descobrir por que algo foi feito ou apenas o deixa sem documentos. É por isso que a empresa precisa tomar mais cuidado para documentar as coisas, enquanto aqueles que sabem ainda estão empregados lá.

Se você está tentando documentar qualquer código que não entende, sugiro que você escreva testes de unidade para testar a funcionalidade. Dessa forma, você entenderá melhor o que o código faz e os próprios testes podem servir como documentação.

Boa sorte!

Quando tento documentar algo que outra pessoa que não está mais no projeto ou na empresa fez, sempre começo a atitude de: Esta é uma caixa preta para todos, inclusive para mim, até que eu precise mudar alguma coisa ou explicá-la a outra pessoa.

A razão pela qual este projeto está na forma de documentação em que você o encontrou é porque a documentação de qualquer trabalho é um pouco secundária à execução. Portanto, documente o que você altera e se você descobriu qual é o campo específico no banco de dados e qual bloco de código faz, se é para o benefício de mais ninguém além do seu.

Você pode escrever testes exploratórios automatizados. Estes têm várias vantagens:

• Você aprende como o sistema funciona enquanto você os escreve

• Eles servem como documentação executável para mais tarde

• Se você executá-los em uma base regular ou até contínua, eles fornecem uma boa rede de segurança para detectar quando as alterações quebram algo ou quando precisam ser atualizadas

Não sei se é possível escrever esse tipo de teste em seu ambiente específico.