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

9

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?

Ben Brocka
fonte

Respostas:

14

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.

Noname
fonte
2
Sim, este é outro para a Regra dos Escoteiros , mas eu também adicionaria - Documento no seu repositório de origem, não em um wiki. Quanto mais próxima a documentação estiver do código-fonte (por JavaDoc ou XML no Visual Studio, por exemplo), maior a probabilidade de ela ser mantida atualizada, além de obter a versão junto com o seu código. Eu não sou o único que gosta rste sphinxpor manter a documentação próxima ao código .
Mark Booth
9

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.

blueberryfields
fonte
8

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á.

ozz
fonte
O controle da fonte foi usado ... muito mal. Nenhuma mensagem de confirmação útil, o SVN foi usado principalmente como backup. Eu posso ver quais arquivos foram adicionados quando (aproximadamente), mas é isso. Nossas personalizações estão todas em sua própria pasta (relatórios alterados, alterações de formulário etc.), mas é o melhor que tenho. Diff não ajuda em nada, pois tudo existe como um arquivo compilado, exceto nossas instruções SQL.
Ben Brocka
5

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:

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.

Spencer Rathbun
fonte
Uma coisa que você não mencionou (que nunca trabalhei com projetos ERB) que fiz no passado com .NET e Java é usar uma ferramenta de engenharia reversa para produzir diagramas de classes e diagramas de sequência automaticamente. Eles foram bastante úteis para isso. Existe algo assim neste caso?
Rig
+1, ótimas informações, você pode me falar sobre o dokuwiki?
PresleyDias
@PresleyDias além do que está no link? Verifique a lista de recursos . Nossa configuração usa o modelo ártico para que o wiki atue como um mini CMS. Se você estiver em um sistema debian, instale manualmente em vez de usar o apt-get ! O Debian usa locais fora do padrão, o que dificulta o gerenciamento.
Spencer Rathbun
2

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!

Bernard
fonte
Infelizmente, não é uma programação tradicional configurada ... principalmente relatórios e alterações de GUI com alguns arquivos estranhos de linguagem proprietários usados ​​para alterar a maneira como o programa atua.
Ben Brocka
2

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.

Karlson
fonte
1

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.

guillaume31
fonte