Como documentar um projeto que já está desenvolvido?

Gostaria de saber quais opções estão disponíveis para documentar um projeto que já foi desenvolvido, pois os desenvolvedores que trabalharam não escreveram sequer uma única página de documentação.

O projeto não possui outros detalhes além de muitas páginas de scripts com funções escritas e modificadas pelos desenvolvedores que trabalharam nesse projeto nos últimos 2 anos. Tudo o que tenho é o esquema do banco de dados e os arquivos do projeto. Gostaria de saber se existe alguma maneira de organizar e documentar esse projeto para que possa ser útil para os desenvolvedores que trabalharão nesse projeto no futuro.

O projeto foi desenvolvido com PHP e MySQL. As funções são mal comentadas, por isso não consigo obter bons resultados quando a executo com doxygen.

Quem estará lendo a documentação? Para que a documentação será usada? Essas são as perguntas mais importantes a serem respondidas. Por exemplo, a documentação para desenvolvedores de manutenção se concentraria mais na estrutura, enquanto a documentação para desenvolvedores que se integram ao produto se concentraria mais em serviços da Web e estrutura de banco de dados.

Em geral, faça a documentação necessária e não mais. Muitas organizações exigem documentação porque alguém insistiu que é uma prática recomendada, mas a documentação acaba acumulando poeira.

Supondo que as pessoas realmente usem a documentação, não tente capturar o código e o banco de dados no nível mais baixo. Os desenvolvedores analisarão o código em busca de minúcias. Em vez disso, concentre-se nos detalhes que não são aparentes no código , por exemplo:

1. Os casos de uso que o produto atende. Isso pode ser difícil, considerando a idade do produto, mas capturar o que o produto deve fazer fornece um contexto vital para leitores e testadores não técnicos. Quem são os concorrentes no mercado (se houver)? Há algo excluído do escopo do produto?
2. Quaisquer requisitos não funcionais claros . Por exemplo, o produto foi escrito para lidar com um determinado volume? Qual a idade dos dados? Onde o cache é usado? Como os usuários são autenticados? Como o controle de acesso funciona?
3. Um diagrama de contexto mostrando a interação com outros sistemas, como banco de dados, fontes de autenticação, backup, monitoramento e assim por diante.
4. (Se conhecido) Riscos e como eles foram mitigados junto com um registro de decisão . Provavelmente, isso é difícil em retrospecto, mas muitas vezes existem decisões críticas que influenciam um design. Capture tudo o que você conhece.
5. Padrões de design comuns ou diretrizes de design . Por exemplo, existe uma maneira padrão de acessar o banco de dados? Existe um padrão de codificação ou nomeação?
6. Caminhos de código críticos , geralmente usando fluxogramas ou atividade UML ou diagramas de sequência. Pode não haver nenhum no projeto, mas esses geralmente são aqueles que os usuários de negócios articularam.

Mesmo se todas essas informações não estiverem disponíveis, comece agora . Os desenvolvedores que vierem depois de você agradecerão.

Bons testes de unidade automatizados ou casos de teste também podem ser uma documentação útil, embora difícil de acessar para pessoas menos técnicas.

Também parece que você precisa fazer uma mudança cultural para incluir a documentação . Comece pequeno, mas, idealmente, o projeto não deve ser "concluído" até que tenha pelo menos um nível mínimo de documentação. Este é provavelmente o passo mais difícil, porque o que precede são coisas que você pode controlar. Isso é algo que os outros devem comprar. No entanto, também pode ser o mais gratificante, principalmente se o próximo projeto que você fizer vier com boa documentação.

No passado, eu gerenciei uma situação como essa, sentando-me com os vários proprietários de produtos ou usuários avançados, analisando seus casos de uso principais e documentando-os com um conjunto de testes. Você pode usá-los como uma linha de base para o sistema quando começar a fazer alterações no futuro. Isso também pode ajudar a identificar áreas do sistema que não possuem um proprietário ou caso de uso e podem ser potencialmente excluídas.

Tudo depende realmente do tamanho do sistema. Se este for um sistema complexo com muitas partes interessadas diferentes, você poderá criar um diagrama de componentes de alto nível detalhando quais recursos existem e onde são satisfeitos. Isso pode ser muito útil para identificar problemas de arquitetura no design do sistema.

Em geral, sugiro evitar a documentação antiquada, pois ela ficará desatualizada e perderá os desenvolvedores líderes no futuro. Eu sempre tento produzir documentação viva na forma de testes que serão mantidos à medida que o sistema evolui.

Primeiramente, quem é seu público-alvo? Desenvolvedores futuros ou outras pessoas de negócios? Com a resposta a essa pergunta em mente:

Como outros já disseram, uma descrição de alto nível é a primeira coisa que você precisa. Explique o que o sistema está tentando fazer no esquema mais amplo das coisas. Explique o que é executado, como se encaixa na rede e se comunica com qualquer outro sistema. Depois, eu examinava cada tela, fazia uma captura de tela e fornecia uma rápida explicação sobre o que a tela faz e como ela interage com outras partes do sistema. Se for para desenvolvedores, mantenha o diálogo como se estivesse explicando o aplicativo a eles pela primeira vez. Afinal, esse é o objetivo do documento (presumo).

Qualquer lógica ou processamento complicado eu usaria um diagrama de estado, diagrama de fluxo de dados ou diagrama de sequência. Definitivamente, faça um diagrama de entidades e, em seguida, um design de esquema de banco de dados (duas coisas diferentes!). Talvez seja um diagrama de classes básico, mas mantenha-o simples, observe apenas as principais coisas que interessam, os desenvolvedores podem descobrir essas coisas observando o código.

Se você está tendo problemas para começar, apenas finja que há outro desenvolvedor na sala ao lado de você, que não sabe a primeira coisa sobre o sistema, eu sou relativamente impaciente e só preciso saber o essencial. Então comece a explicar e escreva o que você diz :)

As sugestões anteriores são boas, mas eu também consideraria pesquisar se sua comunidade de usuários criou alguma documentação ad-hoc. Sua pergunta não especificou se alguma versão do seu 'produto' (existente há dois anos) já foi lançada para os usuários. Se estiver em uso, e não houver documentação oficial, nenhuma documentação foi necessária ou há algum documento 'não oficial' que possa ser rudimentar, mas também provavelmente considerado essencial pelos usuários. Tente pesquisar na Web por artefatos que possam representar APIs críticas, procurar fóruns, perguntar a usuários avançados e pesquisar sites de perguntas e respostas. Se possível, tente escrever uma documentação que atenda a uma necessidade técnica ou comercial.

A questão é: você deseja documentá-lo como está agora ou como deveria ser?

O que li da sua pergunta é que você está pensando na documentação da API e não na documentação do usuário, e o código talvez não seja tão bem mantido e enigmático.

Receio que, se você documentar agora, acabará jogando a maior parte do seu trabalho, depois que o código for refatorado.

Eu adotaria a seguinte abordagem:

• torne a documentação o mais desnecessária possível, aderindo às melhores práticas comuns. Escolha bons nomes de classe, nomes de métodos, nomes de variáveis ​​que você possa entender intuitivamente
• quebrar classes de monstros enormes e / ou funções onde faz sentido
• use comentários do PHPdoc - você pode usar ferramentas para criar documentação da API
• escreva testes para ele: Os testes ajudarão você a entender ou definir o que o código deve fazer.

Agora, você ainda tem coisas não documentadas: esses podem ser os conceitos gerais, a arquitetura etc. Para isso, eu realmente escreveria documentação - mas apenas escreveria o que é realmente útil e útil.