Eu completei um aplicativo Web que é basicamente desenvolvido em PHP e é apenas mais um aplicativo Web regular. Geralmente, quando entrego a versão final da produção, apenas entrego a documentação do código e as informações de arquitetura ao cliente. No entanto, para esse projeto em particular, o cliente insiste em ter os dados completos de entrada e saída do projeto.

Então, eu estou apenas pensando ... Quais são os documentos técnicos e não técnicos obrigatórios que posso fornecer ao meu cliente além das documentações de código e arquitetura?

(Além disso, seria muito legal entrar em contato com o cliente sobre várias estatísticas e dados sobre o projeto, para que ele realmente soubesse a quantidade de trabalho envolvido e o quão realmente legal o produto é.)

Eu acho que a lista deve incluir:

• Os requisitos não técnicos (havia esse documento, certo?)
• Os requisitos técnicos
• Um documento de "decisões" (se houver) explicando por que algumas decisões foram tomadas sobre outras. Isso já pode estar em um documento diferente de requisitos ou arquitetura, mas geralmente fazemos isso separadamente para grandes decisões.
• O código e outros recursos (arquivos de imagem, CSS, etc ...)
• O modelo de banco de dados (como um diagrama, documento, qualquer que seja)
• DDL para criar o banco de dados.
• DML para propagar o banco de dados.
• Um documento explicando a configuração do aplicativo e a solução básica de problemas.
• Uma lista de nomes de usuário importantes e suas senhas (para contas de administrador), bem como instruções sobre como alterar a senha. Idealmente, quando configuram o site pela primeira vez, eles devem ser solicitados a inserir uma nova senha de administrador, mas isso é mais uma coisa de arquitetura.
• Requisitos de sistema e, para aplicativos da web, requisitos mínimos de hospedagem também (o aplicativo precisa do MySQL ou PostgreSQL? Quanta RAM ?, etc ...)

Nem todas essas coisas podem estar disponíveis (ou necessárias) para cada projeto, mas acho que este é um bom guia geral.

Além da resposta realmente boa do FrustratedWithFormsDesigner, gostaria de dizer o que incluem os documentos não técnicos (como fizemos):

• os dados da análise: o que o cliente contou quando você falou sobre os requisitos?

• a oferta que você fez:

  • o documento de requisitos do produto
  • e o documento de especificação funcional

  que juntos atuam como uma espécie de contrato sobre o que você deve fazer e o que espera que
  o cliente entregue durante o desenvolvimento, bem como o tempo e custo estimados.

• a especificação, incluindo protocolos de revisão, casos de uso e planos de teste, resultados de teste

• o design em UML e todos os documentos correspondentes

• a documentação do código fonte (doxygen ou qualquer outra coisa)

• as diretrizes de manual e instalação

• a quantidade real final de recursos (tempo e dinheiro) usados ​​para o projeto, para que você possa escrever uma fatura

• alguns clientes também desejam os protocolos de reunião, o que é uma extensão do "documento de decisões" mencionado acima

Espero que seja isso que você estava procurando.

Siga a documentação que se aplica ao seu projeto, a seguir: Você já pode ter algumas delas.

Documentação técnica:

• Detalhes sobre PHP e informações sobre como é útil para o projeto
• Detalhes sobre o back-end e informações sobre como é útil para o projeto
• Informações sobre conectividade do banco de dados, além de imagens adequadas que descrevem o fluxo de dados
• Informações sobre outras linguagens de programação ou aplicativos envolvidos no projeto, como XML, HTML etc.
• Arquivo de Ajuda do FAQ

Prepare documentos com capturas de tela e destaque o código relevante (se necessário) para o seguinte:

• Informações sobre o aplicativo front-end, como objetos ou controles, propriedades de objetos etc.
• Informações sobre consultas ao banco de dados (se ainda não estiver presente)
• Informações sobre propriedades do banco de dados, como Chave primária, Chave estrangeira etc., e como elas garantem a consistência e a precisão dos dados.
• Guia detalhado em todo o projeto usando capturas de tela de todos os tipos possíveis de tela, usando o front end e o back-end após executá-lo com dados de amostra, sem repetição de dados ou telas semelhantes, em uma ordem lógica.

• Insira dados inválidos e mostre que é impossível fazer isso, pois você realizou a validação de dados no front-end e no back-end.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

• Mostre que não há erro no programa ou inconsistência nos dados se houver uma falha repentina no servidor ou no sistema cliente, explicando o código relevante.

• Depois de fornecer dados de amostra pelo front-end, você pode incluir consultas de amostra no back-end para recuperação direta de dados do servidor e também incluir consultas DML de amostra que podem ajudar a preparar estatísticas vitais de seus dados.

Você deve verificá-las antes de documentá-las, para que, se seu cliente solicitar uma demonstração com dados de amostra, você possa mostrar como o projeto realmente funciona. Além disso, verifique se o código do front-end possui linhas de comentário apropriadas.

• Finalmente, conclua com as estatísticas, como número total de linhas de código, número total de dias passados ​​para o projeto, número total de vezes que você verificou o projeto, uma lista de todos os aplicativos utilizados e outras informações técnicas e não técnicas.

  
  Documentação não técnica:

• Detalhes do licenciamento do projeto, se aplicável.
• Aspectos comerciais do projeto, se aplicável.

Seja cauteloso

A documentação potencial que você poderia fornecer ao cliente é praticamente infinita. O tempo adicional necessário para gerar a documentação que você ainda não possui não é remunerado.

Por que o cliente deseja esta documentação (além do código-fonte)? O que será feito com isso? para quem é isso?

As respostas a essas perguntas ajudarão a limitar o escopo do que entregar.

É fundamental que você e o cliente concordem exatamente sobre qual documentação entregar e se algum esforço adicional será compensado.

Não jogue jogos de adivinhação. A maior parte da documentação técnica seria inútil para o cliente típico (não técnico).

Eu provavelmente dividiria isso em algumas categorias de documentos:

Guias:

• Guia de instalação, como configurar isso em um servidor.
• Guia do administrador, sobre como configurar e executar o aplicativo para obter o desempenho ideal. A segurança também seria algo a ser abordado aqui, apenas para que se saiba quais senhas esse aplicativo possui e usa para executar.

Apoio, suporte:

• Se houver problemas, que tipo de procedimentos você sugeriria? Você está fornecendo suporte por algum período de tempo? Eu provavelmente ainda daria um guia ou dois nessa área, para que alguém saiba algumas das coisas mais fáceis de tentar, como reiniciar serviços ou reiniciar um servidor.

Pontos de integração:

• Existem pontos de integração de terceiros para este aplicativo que o fazem confiar em outros fornecedores que não o seu código?