¿Cómo documentar un proyecto que ya está desarrollado?

Me gustaría saber qué opciones están disponibles para documentar un proyecto que ya se ha desarrollado, ya que los desarrolladores que trabajaron no escribieron ni una sola página de documentación.

El proyecto no tiene más detalles que muchas páginas de scripts con funciones escritas y modificadas por desarrolladores que trabajaron en este proyecto durante los últimos 2 años. Todo lo que tengo es el esquema de la base de datos y los archivos del proyecto. Me gustaría saber si hay alguna forma de organizar este proyecto y documentarlo para que pueda ser útil para los desarrolladores que trabajarán en este proyecto en el futuro.

El proyecto fue desarrollado con PHP y MySQL. Las funciones están mal comentadas, por lo que no puedo obtener buenos resultados cuando lo ejecuto con doxygen.

¿Quién leerá la documentación? ¿Para qué se utilizará la documentación? Estas son las preguntas más importantes para responder. Por ejemplo, la documentación para los desarrolladores de mantenimiento se centraría más en la estructura, mientras que la documentación para los desarrolladores que se integran con el producto se centraría más en los servicios web y la estructura de la base de datos.

En general, haga tanta documentación como sea necesario y no más. Muchas organizaciones requieren documentación porque alguien insistió en que es la mejor práctica, pero la documentación termina acumulando polvo.

Suponiendo que las personas realmente usen la documentación, no intente capturar el código y la base de datos al nivel más pequeño. Los desarrolladores mirarán el código para las minucias. En cambio, concéntrese en los detalles que no son aparentes en el código , por ejemplo:

1. Los casos de uso que cumple el producto. Esto puede ser difícil teniendo en cuenta la antigüedad del producto, pero capturar lo que el producto debe hacer proporciona un contexto vital a los lectores y evaluadores no técnicos. ¿Quiénes son los competidores en el mercado (si los hay)? ¿Hay algo excluido del alcance del producto?
2. Cualquier requisito no funcional claro . Por ejemplo, ¿se escribió el producto para manejar un determinado volumen? ¿Qué edad pueden tener los datos? ¿Dónde se usa el almacenamiento en caché? ¿Cómo se autentican los usuarios? ¿Cómo funciona el control de acceso?
3. Un diagrama de contexto que muestra la interacción con otros sistemas, como la base de datos, las fuentes de autenticación, la copia de seguridad, la supervisión, etc.
4. (Si se conoce) Riesgos y cómo se mitigaron junto con un registro de decisiones . Esto es probablemente difícil en retrospectiva, pero a menudo hay decisiones críticas que influyen en un diseño. Capture cualquiera que conozca.
5. Patrones de diseño comunes o pautas de diseño . Por ejemplo, ¿hay una forma estándar de acceder a la base de datos? ¿Existe un estándar de codificación o nomenclatura?
6. Rutas de código críticas , generalmente usando diagramas de flujo o actividad UML o diagramas de secuencia. Puede que no haya ninguno en el proyecto, pero estos son generalmente los que los usuarios comerciales han articulado.

Incluso si toda esta información no está disponible, comience ahora . Los desarrolladores que vienen después de ti te lo agradecerán.

Las buenas pruebas unitarias automatizadas o los casos de prueba también pueden ser documentación útil, aunque de difícil acceso para personas menos técnicas.

También parece que necesita hacer un cambio cultural para incluir documentación . Comience con poco pero, idealmente, el proyecto no debe "completarse" hasta que tenga al menos un nivel mínimo de documentación. Este es probablemente el paso más difícil porque lo anterior son cosas que puede controlar. Esto es algo que otros deben comprar. Sin embargo, también puede ser lo más gratificante, especialmente si el próximo proyecto que realiza incluye buena documentación.

En el pasado, he manejado una situación como esta sentándome con los diferentes propietarios de productos o usuarios avanzados, revisando sus casos de uso principales y documentando estos con un conjunto de pruebas. Puede usarlos como línea de base para el sistema cuando comience a realizar cambios en el futuro. Esto también puede ayudar a identificar áreas del sistema que no tienen un propietario o caso de uso y que posiblemente se eliminen.

Todo depende del tamaño del sistema realmente. Si este es un sistema complejo con muchas partes interesadas diferentes, podría crear un diagrama de componentes de alto nivel que detalle qué capacidades existen y dónde se satisfacen. Esto puede ser muy útil para identificar problemas arquitectónicos en el diseño del sistema.

En general, sugiero evitar la documentación pasada de moda porque quedará desactualizada y perderá el liderazgo de los desarrolladores en el futuro. Siempre trato de producir documentación viva en forma de pruebas que se mantendrán a medida que el sistema evolucione.

Primero lo primero, ¿quién es su público objetivo? ¿Futuros desarrolladores u otras personas de negocios? Con la respuesta a esa pregunta en mente:

Como otros han dicho, una descripción de alto nivel es lo primero que necesita. Explique lo que el sistema intenta hacer en el esquema más amplio de las cosas. Explique en qué se ejecuta, cómo encaja en la red y cómo se comunica con cualquier otro sistema. Luego revisaría cada pantalla, la capturaría y daría una explicación rápida de lo que hace la pantalla y cómo interactúa con cualquier otra parte del sistema. Si es para desarrolladores, manténgalo conversacional como si les estuviera explicando la aplicación por primera vez. Después de todo, ese es el punto del documento (supongo).

Cualquier procesamiento o lógica complicada usaría un diagrama de estado, diagrama de flujo de datos o diagrama de secuencia. Definitivamente haga un diagrama de entidad, luego un diseño de esquema de base de datos (¡dos cosas diferentes!). Tal vez sea un diagrama de clase básico, pero manténgalo simple, solo tenga en cuenta las cosas principales que son de interés, los desarrolladores pueden resolver esas cosas mirando el código.

Si tienes problemas para comenzar, solo finge que hay otro desarrollador allí en la habitación junto a ti, que no sabe lo primero sobre el sistema, estoy relativamente impaciente y solo necesito saber lo esencial. Luego comienza a explicar y escribe lo que dices :)

Todas las sugerencias anteriores son buenas, pero también consideraría investigar si su comunidad de usuarios ha creado alguna documentación ad-hoc. Su pregunta no especificó si alguna versión de su 'producto' (existente desde hace dos años) ha sido lanzada alguna vez a los usuarios. Si ha estado en uso y no hay documentación oficial, entonces no se ha necesitado ninguna documentación o hay algún documento 'no oficial' que puede ser rudimentario, pero que probablemente los usuarios lo consideren esencial. Intente buscar en la web artefactos que puedan representar API críticas, buscar foros, preguntar a usuarios avanzados y buscar sitios de preguntas y respuestas. Si es posible, intente escribir documentación que satisfaga una necesidad técnica o comercial.

La pregunta es, ¿desea documentarlo como es ahora o como debería ser?

Lo que leí de su pregunta es que está pensando en la documentación de la API y no tanto en la documentación del usuario, y el código tal vez no está tan bien mantenido y es críptico.

Me temo que si documenta ahora, terminará tirando la mayor parte de su trabajo, una vez que se refactorice el código.

Tomaría el siguiente enfoque:

• haga que la documentación sea innecesaria tanto como sea posible al adherirse a las mejores prácticas comunes. Elija buenos nombres de clase, nombres de métodos, nombres de variables que pueda entender intuitivamente
• desglosar grandes clases de monstruos y / o funciones donde tenga sentido
• use comentarios PHPdoc: puede usar herramientas para crear documentación de API
• escribir pruebas para ello: las pruebas lo ayudarán a comprender o definir qué debe hacer el código.

Ahora, todavía tiene cosas sin documentar: estos pueden ser los conceptos generales, la arquitectura, etc. Para esto, realmente escribiría documentación, pero solo escribiría lo que es realmente útil y útil.