Fui encarregado de liderar o esforço de documentação de um produto de software existente, totalmente não documentado - que recursos existem para me ajudar?

Sou desenvolvedor de software em uma empresa de tecnologia. Fui encarregado de liderar o esforço de documentação do produto em que trabalho. O objetivo é produzir documentação interna para o desenvolvedor, e o projeto se espalha para o lado comercial, onde abrange a documentação de requisitos.

Este projeto é desafiador. Especificamente, estou lidando com um produto que: - existe há muito tempo, há pelo menos 6 anos. - não tem outra forma de documentação além de algumas peças pequenas e desatualizadas aqui e ali. - possui comentários no código, mas são técnicos e não transmitem nenhum comportamento geral (mesmo no lado técnico). - em consequência de ter pouca ou nenhuma documentação, muitas vezes é desnecessariamente complexo

Além disso, não nos foi dado muito tempo para trabalhar neste projeto.

Não possuo documentação formal ou formação, treinamento ou experiência em redação. Eu demonstrei alguma habilidade na escrita / comunicação em todo o escritório, e pode ser por isso que fui designado para este projeto.

Compartilhe seu conselho ou recomendação de recursos para me ajudar a preparar e lidar com este projeto. Estou procurando referências a livros / site / fóruns / o que for, para me ajudar a elaborar um plano com marcos, aprender sobre as melhores práticas, delegação de tarefas, modelos, adesão, etc.

Espero especificamente os recursos direcionados ou dando menção especial à introdução de boa documentação para projetos existentes e não documentados .

Eu costumo usar um wiki e apenas enviar spam por lá enquanto passo pelo processo de descoberta. Wiki porque você obtém pesquisa e histórico, além de funções de edição de equipe. A ferramenta exata é menos importante do que ter uma pesquisa em funcionamento e fazer com que todos a usem. Espere que seja muito duro no início, mas incentive as pessoas a fazerem essas anotações bruscas à medida que avançam, porque isso é tudo que você obterá primeiro.

Algumas coisas que ajudam muito:

• tem um editor. Você, provavelmente, a princípio, mas se você tiver o orçamento, faça parte do trabalho de alguém. Escolha alguém que seja bom em linguagem, em vez de um gênio técnico. Edite para maior clareza do que perfeição - você deseja incentivar as pessoas a escrever boas entradas, mas precisará orientá-las primeiro.
• use diagramas, mas determine que uma ferramenta relevante seja usada, a imagem seja gerada e o arquivo de origem anexado à página. Dessa forma, as pessoas podem editar sua imagem usando a ferramenta adequada em vez do MS-Paint. Poucas coisas sugam mais do que um diagrama realmente bom criado no Visio para o qual você não tem mais o documento de origem, apenas um PNG extraído dele.
• Incentive o rearranjo e a edição. Mesmo que não seja ótimo no começo, você precisa que as pessoas coligam informações e corrijam erros. Orientar as pessoas a fazer isso bem.
• traga isso à tona nas reuniões semanais da equipe. Pegue a lista de edições recentes antes de elogiar as pessoas que adicionaram algo útil e pergunte por que as que não o fizeram não o fizeram.

Eu comecei com uma imagem de máquina virtual do MediaWiki no passado porque é muito rápido e fácil de começar, para que as pessoas que dizem "é muito difícil" não recebam nenhuma tração inicial.

Se o seu idioma / ambiente o suportar usando ferramentas do tipo JavaDoc / NDoc para extrair os comentários à medida que você os adiciona, é uma boa abordagem de baixo nível. Mas isso é menos útil do que a documentação de alto nível, e mesmo que as ferramentas suportem a adição de itens de nível superior, criá-lo do nada usando apenas essas ferramentas é desnecessariamente trabalhoso.

Se você está documentando o código em si e não está documentando o usuário final, o Doxygen é uma ótima ferramenta se suas linguagens de desenvolvimento forem suportadas. Você o executa no seu código e cria um site listando todas as suas funções, classes, etc. Em seguida, você pode adicionar comentários de código especialmente formatados para agrupar itens e adicionar mais detalhes. É uma ótima maneira de documentar incrementalmente uma base de código.

No que diz respeito à documentação do código, se o Doxygen não atender às suas necessidades, existem muitas ferramentas alternativas disponíveis. A Wikipedia possui uma lista de quase 50 dessas ferramentas e inclui detalhes de suas funcionalidades e suporte a idiomas.

Isenção de responsabilidade: Estou associado a uma das ferramentas, Imagix 4D .

Estas são apenas algumas idéias que podem ser úteis em algum nível:

Você já pensou em que formato essa documentação terá no final: Será um documento do Word, um DVD, um site com uma série de páginas que detalham o aplicativo, uma ferramenta de blog que apenas detalha os detalhes do aplicativo à medida que se mergulha usando algum sistema de gerenciamento de documentos disponível como o Share Point ou algo mais? Obter resultados seria um exemplo de um livro on-line que é uma série de páginas, por exemplo.

Que tipo de controle de versão e processo de edição você deseja que esta documentação seja, é outro problema que vale a pena ponderar antes de você se aprofundar nisso. Como você deseja lidar com atualizações e alterações.

É provável que o feedback seja outra dimensão interessante sobre isso, pois o que você criar, provavelmente haverá mais do que algumas críticas, e quão bem essas mudanças serão priorizadas e otimizadas é outra questão que eu consideraria antes de lançar a primeira versão.

Boa sorte!

Construir Documentação, como construir todos os outros tipos de software, é um processo inerentemente complexo.

É por isso que os desenvolvedores de software inventaram os métodos Agile.

A documentação é apenas um software sem um compilador. Os mesmos métodos para projetos de software se aplicam a projetos de documentação. Exatamente o mesmo raciocínio.

Ao escrever um software, você começa com casos de uso (ou histórias de usuários). A documentação não é diferente.

Você prioriza os casos de uso com um orçamento aproximado.

Você tem sprints.

Você tem lançamentos.

Você faz garantia de qualidade - teste - revisão - correção e relançamento.

É exatamente como criar software.

Quem são seus usuários? Que problemas eles têm? Como o documento resolverá o problema deles? Prioritizar. Arrancada. Eventualmente, você liberará.