En esta segunda parte de la crónica referente a la documentación de sistemas, continuo con la contraparte de las frases que la gente del gremio informático utiliza para exponer los motivos por los cuales no es útil, no se debe o no tiene caso generar dicha documentación.
En la entrega anterior planteo un cuestionamiento al final: ¿Cómo se puede encontrar el gusto a la tarea de documentar? Y la respuesta adelantada fue: ponerte en el papel de quien la necesita.
Pongamos el siguiente escenario para fines de esta discusión. Eres una recién egresada y has encontrado tu primera oferta laboral, para participar en la creación de un sistema de gestión de un proceso documental que, además de seguir el flujo del proceso de negocio según las etapas definidas, el sistema deberá ser capaz de almacenar y permitir consultar los distintos documentos y evidencias que se van generando a lo largo del flujo de proceso.
Hay documentación útil que no necesariamente es un producto de trabajo
Supongamos que te asignan el módulo que gestionará los documentos. Tu primer entregable consiste en crear una biblioteca de funciones/paquete que permita registrar un documento por clave de proceso, identificador del documento, nombre y descripción del mismo, la fecha de creación y el documento per se. Como eres una novata ejemplar, entregas tus productos en tiempo y forma. Cuando viene la revisión, te comentan:
-aquí identamos el código con tabulador y tu código trae espacios. Las tablas de de base de datos las nombramos en singular, las tuyas tienen mezcla de plurales y singulares. Las variables que refieren a datos que se persistirán en base de datos deben tener el mismo nombre que las columnas en las tablas…
¿Cómo se puede llegar a este escenario? En tres sencillos pasos -faltas-. No preguntaste las reglas y/o acuerdos de estándares de trabajo (tu falta), no te los comunicaron (falta del responsable), y finalmente, no está definido por escrito (falta del procedimiento).
Si eres novata, es «normal» no saber que existan esos acuerdos; si el resto del equipo no te comunica que existen, es falta del equipo asumir que los conoces; lo que es peor, la ausencia de estos acuerdos por escrito, desde la definición del proceso o los artículos por sí mismos, propicia que el equipo se base en acuerdos al día, por costumbre y en confiar en la memoria de sus miembros.
¿Cuál es la ventaja de tener estos acuerdos por escrito (documentados)?
- Las definiciones no dependen de la opinión o del estado de ánimo de los integrantes de un equipo.
- Son reproducibles entre diferentes proyectos.
- Propicia la estandarización de los productos de trabajo.
- Reduce la curva de aprendizaje de los nuevos integrantes.
- Incluye (normalmente) mecanismos de resolución de controversias, revisión y actualización de los acuerdos.
Con un documento y procedimiento así, cuando te integras al equipo, si no hay alquien que te pueda explicar o detallar los estándares, el documento está disponible para tu consulta, de hecho, es lo ideal, porque así no se invierte tiempo del resto del equipo en explicar algo que cada integrante puede leer a su conveniencia.
Vemos aquí un ejemplo de un documento que no tiene nada qué ver (aparentemente) con el trabajo que desempeñas, con el producto que entregarás o sus flujos, y que sin embargo, es útil tener.
Comentarlo te tomaba menos de un minuto
Han pasado algunos meses, y ahora ya estás integrada con el equipo. Ya conoces los estándares de trabajo y te has acoplado sin mayores contratiempos. Raúl, uno de los integrantes, debe ausentarse del proyecto y no podrá completar el módulo en el que está trabajando. La dirección del proyecto considera que tienes la capacidad para retomarlo y culminarlo en tiempo, de forma que te lo asignan.
Dado que todo el equipo sigue los mismos estándares de programación, encontrar los componentes y ambientar tu equipo para continuar con el trabajo de Raúl fue sencillo, ya estás lista para iniciar. Tu primera tarea es completar el módulo que inicia los trámites del flujo de proceso. El módulo ya está integrado al flujo principal e incluso están haciendo uso de las funciones que generaste en tu primer entregable. Para finalizar esta etapa, el módulo debe:
- Validar que se cuenta con todos los documentos necesarios para iniciar el flujo de proceso.
- Realizar una doble verificación en pantalla, mostrando un mensaje al usuario indicándole que está por iniciar un proceso y solicitando que confirme (o cancele) la operación.
- Enviar un correo eletrónico a los involucrados en el proceso si la operación se confirma y el flujo de proceso es iniciado.
Examinas el código fuente para localizar el punto donde debes agregar estas partes y te enfocas en finalizar el trabajo. Como todo el código sigue los estándares acordados, está bien estructurado y sigue las prácticas de la industria, no se te hizo complicado seguir el flujo. Conforme lo esperado, completas las tareas en algunos días y procedes a validar los componentes. Generas un nuevo proceso, agregas los documentos, se presenta la confirmación en pantalla, la aceptas y recibes el correo electrónico conforme la definición. Envías tus componentes a pruebas.
Dos días después, eres convocada a una junta con el equipo de calidad y te dan el siguiente reporte de hallazgos:
– El módulo no valida que si la fecha de creación corresponde al último día hábil del mes, la fecha de registro debe quedar asentada como el primer día hábil del mes siguiente.
Para no perder tiempo, intentas localizar a Raúl para preguntarle en qué parte debería estar esta validación pues no la identificaste durante las actividades para completar el trabajo pendiente, sin embargo, no logras contactarlo. Te avocas a hacer un debug activo e ir siguiendo el proceso para identificar en qué momento debes ajustar la fecha, lo localizas. Ahora tienes un dilema: el código sí incluye instrucciones que están validando la fecha de registro y la regla de negocio que te reportaron como no existente, pero cuando haces la prueba en efecto, parece no funcionar, aunque al examinar el código, no ves errores en la ejecución.
Durante la pausa para un refrigerio comentas tu situación con el equipo; afortunadamente, Azucena, que estuvo revisando esos requerimientos con Raúl te comenta que, dado que el sistema se usará en más de una locación con distintos husos horarios, se decidió manejar todas las fechas y horarios con base en el GTM-6, por lo que debes ajustar las pruebas a que coincidan con esos horarios.
¿Qué pasó aquí? Aunque todo el código sea correcto, esté bien estructurado y se sigan las mejores prácticas, el código fuente no refleja las decisiones de diseño, de negocio o la configuración necesaria de los componentes. Este tipo de definciones caben en un comentario en el código, que más que indicar qué hace, informa el porqué las instrucciones están así, es decir, regresando a nuestro ejemplo, informar el porqué usar GMT-6 en lugar del huso horario corriente. Comentarios de este estilo, le toman a quien desarrolla unos instantes, pero le ahorra a quien revisa y tiene que dar mantenimiento al mismo, horas o días de trabajo.
Ahora que has visto esta segunda parte de la crónica, supongo que ya podrás inferir de qué va la siguiente y última entrega. Continuaré abordando escenarios donde un pequeño esfuerzo de documentación (de toda índole) habría facilitado el trabajo e incrementado la productividad del equipo.
Deja un comentario