Documentación

Primero lo primero: ¿de qué documentación estoy hablando? Tenemos diferentes tipos de documentos que cubren absolutamente todo lo que puede ser documentado: qué, quién, cómo, cuándo y por qué.

Quiero enfocarme en la documentación interna del equipo desarrollo, aquella que dice cómo se deben hacer las cosas. Documentación que debería responder, por ejemplo, a este tipo de preguntas: ¿cómo me conecto a una base de datos? ¿cómo hago una consulta? ¿cómo armo una pantalla? ¿cómo le presento los mensajes al usuario?

Si se pretende cierta unicidad entre diferentes módulos de un sistema o entre diferentes desarrollos de una misma empresa implementados por diferentes personas es indispensable un marco de trabajo, un framework propio que se montará sobre la herramienta de desarrollo que estemos utilizando. Este framework constará no sólo de herramientas de código (clases, interfaces y demás) sino de prácticas comunes para organizar proyectos, carpetas, nomeclatura, etc.

Ahora, una cosa es que este framework exista y otra el grado en que es efectivamente utilizado por los desarrolladores. Y esto dependerá en buena medida de la documentación que exista acerca del mismo. Por ejemplo, cuando un nuevo integrante se incorpora al equipo es indispensable poder entregarle un manual que detalle los estándares de estilo utilizados, las herramientas que puede y debe utilizar para llevar a cabo las tareas comunes, los estándares visuales de la interfaz del usuario. Una vez estudiados e internalizados estos documentos podrá comenzar a trabajar....

No, mentira.

Conozco (de oídas) de empresas en las que esta documentación existe. Incluso me han contado de casos en los que es frecuentemente actualizada (por ejemplo para cumplir con alguna norma o estándar certificado). Actualizados o no, los usos más frecuentes de este tipo de papeles son la elevación de monitores de plasma (¿vieron que en algunos modelos los soportes son demasiado bajos y no son ajustables?), la recolección de polvo, la decoración de bibliotecas y estanterías (quedan muy feas cuando están vacías) y otros por el estilo.

Cuando un nuevo integrante se suma al equipo, es usualmente depositado frente a una computadora y una pila de CD's de instalación. Ése es su primer día. A fin de evitar que quede atrapado en los brazos de morfeo se le entregará la documentación de la que hablaba en el párrafo anterior, si es que existe (usualmente con efectos opuestos a los que se prentendían). Si no existe y la gente no está muy ocupada, charlará un largo rato. Si la gente está ocupada... Consejo: no está de más llevar una revista el primer día. Con suerte podrá abrir el proyecto antes de irse a casa.

El segundo día lo verá enfrentado a un mar de código y (con suerte) una tarea entre manos. Si la documentación existe y ha sido leída, e incluso retenida, probablemente sea encontrada tan irrelevante como la tarea a desarrollar.

Pero las cosas funcionan, uno se desarrolla, aprende... el secreto está en la documentación. La verdadera documentación.

En algún momento, por obligación, lástima o caridad, alguien se acercará al nuevo integrante y le dará una visión general de lo que está viendo. Con eso podrá investigar un poco más en el código. Después de comer (charlando sobre la estructura del proyecto) se baja un poco más a detalle, siempre de palabra, "después lo ves en el código"... y así.

¿Qué pasa cuando no hay nadie que pueda llevar a cabo esa capacitación informal? Lo mismo, pero es mucho más lento. El nuevo integrante empezará a mirar primero la estructura general y bajará al detalle de a poco. O tal vez empiece buscando el lugar donde tiene que realizar su pequeña asignación y siga las ramificaciones desde ahí... las técnicas son tan variadas como las personas.

Pero... ¿de qué se trata este artículo? ¿documentación interna? ¿establecimos que no sirve? ¿listo?

Arriesgo una teoría. Lo que muchas veces sucede (recalco: por lo menos en mi personalísima experiencia) es que la documentación es requerida por alguien ajeno al equipo de desarrollo: el líder de proyecto, el gerente de sistemas, una norma, una metodología de trabajo (que nos dice "es necesario tal y tal y tal otro documento"), etc. En estos casos la documentación está obviamente orientada a cumplir con ese objetivo o requerimiento en el momento en que debe ser cumplido. Servirá para eso y nada más. Cuando intentamos utilizarla para otra cosa (por ejemplo para instruir "al nuevo") fracasa como fracasarían nuestros sistemas de facturación si intentáramos hacer que controlen los motores de un barco.

Si necesitamos tener documentación interna de referencia, tendremos que pensar en esa situación y crearla con ese único objetivo en mente. Recalco **necesitamos**. Como todos los sistemas, y la documentación ES un sistema, si no hay una necesidad real, jamás será utilizada. Si el equipo es estable y las incorporaciones esporádicas, será mucho más fácil capacitar al nuevo de palabra, y es lo que sucederá. Si el código es claro, de manera que en cada capa de la aplicación el código existente sirve de referencia para lo nuevo, tampoco habrá nada más que consultar, y así. Ahora, si en el equipo hay alta rotación habrá que bajar esa charla informal de la que hablábamos a papeles, o darla todos los días (cualquiera prefererirá lo primero). Si estamos trabajando en mantenimiento con mucho código heredado, enmarañado y confuso, será mejor que cada vez que descubramos alguna estructura o subsistema lo anotemos prolijamente en un documento aparte, porque volver a leerlo desde el código no será fácil.

Les aseguro que así es más fácil, e incluso entretenido documentar.

Ensayo una lista de "buenas prácticas informales":

• La primera fuente de documentación interna es el código. La respuesta más frecuente a "¿cómo se hace tal cosa?" es "fijáte en tal lado y seguí la idea". Tratemos de documentar con el código o en el código.
• Si hay que documentar tareas comunes, pocas palabras y muchos ejemplos extraídos de algún sistema.
• Si hay que documentar estructuras de capas o flujo de ejecución a través de diferentes módulos, lo más sencillo de entender son los gráficos, con referencias a la ubicación en el proyecto del código correspondiente. Son molestos de hacer y mantener, es cierto. Pero relatar el proceso de impresión de un reporte desde la toma de parámetros hasta el deslpiegue del documento es mucho más difícil.
• Ubicar la documentación donde se la necesita. Es muy común tener una enorme bolsa llamada "documentos" donde hay que revolver para encontrar algo. Si tengo un documento que explica el acceso a datos, ¿por qué no adjuntarlo al proyecto junto con el código de la capa de acceso a datos?
• Tratar de que sea una tarea constante, no esporádica, que cualquiera pueda corregirla.
• Versionar, todo.