He completado una aplicación web que se desarrolla básicamente en PHP y es solo otra aplicación web normal. Por lo general, cuando entrego la versión de producción final, simplemente entrego la documentación del código y la información de la arquitectura al cliente. Sin embargo, para este proyecto en particular, el cliente insiste en tener los datos completos de entrada y salida del proyecto.

Así que me pregunto ... ¿Cuáles son los documentos técnicos y no técnicos obligatorios que puedo dar a mi cliente aparte del código y las documentaciones de arquitectura?

(También sería genial hablar con el cliente sobre diversas estadísticas y datos sobre el proyecto para que realmente sepa la cantidad de trabajo involucrado y cuán genial es el producto en realidad).

Creo que la lista debería incluir:

• Los requisitos no técnicos (había tal documento, ¿verdad?)
• Los requisitos técnicos
• Un documento de "decisiones" (si hubiera uno) que explica por qué algunas decisiones se tomaron sobre otras. Esto ya puede estar en un documento de requisitos o arquitectura diferente, pero generalmente lo hacemos por separado para Big Decisions.
• El código y otros recursos (archivos de imagen, CSS, etc.)
• El modelo de base de datos (como diagrama, documento, lo que sea)
• DDL para crear la base de datos.
• DML para sembrar la base de datos.
• Un documento que explica la configuración de la aplicación y la solución de problemas básicos.
• Una lista de los nombres de usuario importantes y sus contraseñas (para cuentas de administrador), así como instrucciones sobre cómo cambiar la contraseña. Idealmente, cuando configuran el sitio web por primera vez, se les debe solicitar que ingresen una nueva contraseña de administrador, pero esto es más una cuestión de arquitectura.
• Requisitos del sistema, y ​​para aplicaciones web, requisitos mínimos de alojamiento también (¿La aplicación necesita MySQL o PostgreSQL? ¿Cuánta RAM ?, etc ...)

No todas estas cosas podrían estar disponibles (o ser necesarias) para cada proyecto, pero creo que esta es una buena guía general.

Además de la muy buena respuesta de FrustratedWithFormsDesigner, me gustaría decir qué incluyen los documentos no técnicos (como lo hicimos nosotros):

• los datos de análisis: ¿qué le dijo el cliente cuando habló por primera vez de los requisitos?

• la oferta que hizo:

  • el documento de requisitos del producto
  • y el documento de especificación funcional

  que en conjunto actúan como una especie de contrato sobre lo que debe hacer y lo que espera que
  el cliente entregue durante el desarrollo, así como el tiempo y el costo estimados.

• la especificación que incluye protocolos de revisión, casos de uso y planes de prueba, resultados de pruebas

• el diseño en UML y todos los documentos correspondientes

• la documentación del código fuente (doxygen o lo que sea)

• el manual y las pautas de instalación

• la cantidad real final de recursos (tiempo y dinero) utilizados para el proyecto, por lo que puede escribir una factura

• algunos clientes también quieren los protocolos de reunión, que es una extensión del "documento de decisiones" mencionado anteriormente

Espero que eso sea lo que estabas buscando.

Siga la documentación que corresponda para su proyecto entre las siguientes: es posible que ya tenga algunas de ellas.

Documentación técnica:

• Detalles sobre PHP e información sobre cómo es útil para el proyecto
• Detalles sobre el back-end e información sobre cómo es útil para el proyecto.
• Información sobre la conectividad de la base de datos junto con imágenes adecuadas que representan el flujo de datos.
• Información sobre otros lenguajes de programación o aplicaciones involucradas en el proyecto como XML, HTML, etc.
• Preguntas frecuentes Archivo de ayuda

Prepare documentos con capturas de pantalla y resalte el código relevante (si es necesario) para lo siguiente:

• Información sobre la aplicación front-end como objetos o controles, propiedades de objetos, etc.
• Información sobre consultas de la base de datos (si aún no está presente)
• Información sobre las propiedades de la base de datos como Clave primaria, Clave externa, etc. y cómo aseguran la consistencia y precisión de los datos.
• Guía detallada a lo largo del proyecto mediante el uso de capturas de pantalla de todo tipo de pantalla posible utilizando tanto el front-end como el back-end después de ejecutarlo con datos de muestra, sin repetición de datos o pantallas similares, en un orden lógico.

• Ingrese datos no válidos y demuestre que es imposible hacerlo, ya que ha realizado la validación de datos en el front-end y el 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. */

• Muestre que no hay error en el programa o inconsistencia en los datos si hay una falla repentina en el servidor o sistema del cliente al explicar el código relevante.

• Después de proporcionar datos de muestra a través del front-end, puede incluir consultas de muestra en el back-end para la recuperación directa de datos del servidor y también incluir consultas DML de muestra que pueden ayudar a preparar estadísticas vitales de sus datos.

Debe verificar esto usted mismo antes de documentarlos para que si su cliente solicita una demostración con datos de muestra, pueda mostrar cómo funciona realmente el proyecto. Además, asegúrese de que su código de front-end tenga líneas de comentarios apropiadas.

• Finalmente, concluya con estadísticas como el número total de líneas de código, el número total de días dedicados al proyecto, el número total de veces que ha verificado el proyecto, una lista de todas las aplicaciones utilizadas y otra información técnica y no técnica.

  
  Documentación no técnica:

• Detalles de licencia del proyecto, si corresponde.
• Aspectos comerciales del proyecto, si corresponde.

Sé cauteloso

La documentación potencial que podría proporcionar al cliente es prácticamente infinita. El tiempo adicional requerido para generar la documentación que aún no tiene no se paga.

¿Por qué el cliente quiere esta documentación (además del código fuente)? ¿Qué se hará con él? ¿Para quién?

Las respuestas a estas preguntas ayudarán a reducir el alcance de qué entregar.

Es fundamental que usted y el cliente acuerden exactamente qué documentación entregar y si se compensará cualquier esfuerzo adicional.

No juegues a adivinanzas. La mayoría de la documentación técnica sería inútil para el cliente típico (no técnico).

Probablemente dividiría esto en algunas categorías de documentos:

Guías:

• Guía de instalación, cómo configurarlo en un servidor.
• Guía del administrador, sobre cómo configurar y ejecutar la aplicación para un rendimiento óptimo. La seguridad también sería algo para cubrir aquí solo para que se sepa qué contraseñas tiene esta aplicación y qué utiliza para ejecutarse.

Apoyo:

• Si hay problemas, ¿qué tipo de procedimientos sugeriría? ¿Está brindando soporte durante algún tiempo? Probablemente todavía daría una guía o dos en esta área para que alguien más conozca algunas de las cosas más fáciles de intentar, como reiniciar los servicios o reiniciar un servidor.

Puntos de integración:

• ¿Existen puntos de integración de terceros para esta aplicación que la hacen depender de otros proveedores además de su código?