Cómo documentar un pequeño sitio web existente (aplicación web), por dentro y por fuera?

Question

Tenemos una "aplicación web" que se ha desarrollado en los últimos 7 meses. El problema es que no estaba realmente documentado. Los requisitos consistían en una pequeña lista con viñetas de la reunión inicial de hace 7 meses (es más una declaración de "objetivos" que requisitos de software). Se ha recopilado una serie de características que se derivan de pequeños debates verbales o de chat.

El desarrollador se va muy pronto. Escribió todo él mismo y conoce todas las peculiaridades y reglas subyacentes de cada página, pero nadie más sabe mucho más que el lado de la interfaz de usuario; que, por supuesto, es la parte fácil, ya que está hecho para ser intuitivo para el usuario. Pero si alguien necesita reparar o agregarle una función, todo es una caja negra. El código tiene algunos comentarios mínimos y, por supuesto, lo bueno de las aplicaciones web es que la barra de direcciones te indica la dirección correcta para solucionar un problema o actualizar una página.

Pero, ¿cómo debe el desarrollador ir sobre la documentación de esta aplicación web? Está un poco perdido en cuanto a dónde comenzar. Como desarrolladores, , ¿cómo documenta completamente sus aplicaciones web para otros desarrolladores, mantenedores y usuarios de nivel administrativo? ¿Qué enfoque usa, dónde comienza, qué software usa, tiene una plantilla?

Una idea de magnitud: usa PHP, MySQL y jQuery. Tiene alrededor de 20-30 archivos principales (frontend), junto con aproximadamente 15 archivos incluidos y un par de carpetas de algunos activos, por lo que en general es una aplicación bastante pequeña. Interactúa con 7 tablas MySQL, cada una de ellas bien nombrada, así que creo que el final de la base de datos es bastante autoexplicativo. Hay un archivo config.inc.php con definiciones de constelaciones como los detalles de usuario de MySQL, algunos de/a correos electrónicos y URL que PHP utiliza para insertar en correos electrónicos y páginas (rutas relativas y absolutas, basicamente). Hay algunos AJAX a través de jQuery.

favor comentar si hay cualquier otra información que le ayudaría a ayudarme y yo le alegra editarlo en.

---

El desarrollador abandona el viernes. Sin embargo, puede dedicar la mayor parte de sus 24 horas restantes a esta tarea de documentación. Entonces, sí, las cosas son sombrías, pero las 24 horas son bastante ... ¿verdad? : - \

Answer 1

Comenzaría enumerando las características principales que la aplicación implementa actualmente (actualice los puntos iniciales).

Luego, para cada punto, anote los requisitos principales asociados con ese punto.

Para cada requisito, anote:

• Cualquier cosa peculiar de ese requisito particular
• Cuando en el código que se implementa el requisito (que php, archivos inc, tablas)

Este le dará algo de una jerarquía de trazabilidad

Característica => Requisito => Implementación

También proporcionará un buen marco para empujar recuerdos y escribir gotcha's.

A continuación, comente cada página de php y de inc.

Comience con un encabezado que describa el propósito y qué requisito (s) de la lista anterior se satisfacen (trazabilidad inversa del código al requisito).

Revise cada archivo php/inc y comente las acciones/decisiones/bucles principales que indiquen lo que intentan lograr y cualquier consideración de diseño que se asuma (por ejemplo, "se supone que la entrada se validó en el paso anterior") .

Al comentar el código fuente, es posible que desee utilizar una herramienta como PHPDoc para que pueda generar la documentación de los comentarios.

Answer 2

Un enfoque podría ser organizar una serie de reuniones de entrega. En estos, el desarrollador debería explicar el código de cada sección.

Podría escribir algunas notas en preparación para esto, pero que los otros desarrolladores tomen minutos también podría ayudarlos a entender el código. También estas reuniones serían una oportunidad para hacer preguntas sobre aspectos que no están claros.

No intente hacer todo el sitio de una vez. Divídala en dos trozos más pequeños agrupados de alguna manera, por función o por área. Esto significa que tus otros desarrolladores no son bombardeados con demasiada información de una sola vez, el desarrollador original puede concentrarse en un área a la vez y tienes la oportunidad de hacer un seguimiento después de la reunión.

Incluso si nada "se pega" de inmediato, habrá cierta familiaridad con el sitio cuando vuelva a visitarlo más tarde.

Otro enfoque podría ser que el desarrollador realice una serie de breves presentaciones en el sitio y cómo fue construido. Esto podría llevarlo a recordar por qué tomó los enfoques que hizo. Esto es invaluable cuando se mira el código. Si sabes qué problema estaba tratando de resolver, es mucho más fácil de entender.