- No hay absolutamente nada documentado. Las especificaciones son diagramas sin estándares escritos con lapicera por algún co-worker, y como mucho disponemos de e-mails para saber qué hay que hacer.
- Hay algo documentado pero vagamente. Algunos comentarios que nos ayudan en el código, y quizás algún sistema que lleva tracking de las tareas a hacer. Pero nada que diga qué terminamos haciendo, cambiando, etcétera. Obviamente, los manuales son inexistentes o se encuentran totalmente desactualizados. Los requerimientos son correos electrónicos, y UML son tres letras juntas puestas en mayúsculas.
- Absolutamente todo está documentado hasta el hartazgo. Tanto que cada requerimiento simple nos lleva horas y horas de documentar, y muchas veces lleva más tiempo eso que realizar el desarrollo en sí. Todo lo que no esté escrito no se realizará, y si a alguien se le corrió una coma, el sistema pasará de facturar productos informáticos a informar sobre la producción de facturas de dulce de leche en los locales de venta. La gente discute y lo único que quiere es tener la razón, y no hacer el trabajo ni ir hacia adelante.
Obviamente hay otros escenarios pero creo que estos tres son los más conflictivos en cuanto al "problema" de la documentación. Nótese cómo puse que documentar es un problema. Lo cierto es que es tanto una disciplina útil y beneficiosa como puede ser un problema molesto de todos los días.
Vamos a ver primero qué podemos documentar:
- Requerimientos
- Diagramas de Actividad
- Casos de Uso
- Diagramas de Secuencia
- Diagramas de Clase
- Diagramas de Colaboración
- Diagramas de Componentes
- Diagramas de Paquetes
- Diagramas de Arquitectura
- Implementaciones
- Tickets
- Casos de Uso de Prueba
- Código
- Bases de Datos
- Documentos (sí, entramos en Inception)
- Minutas de Reuniones
- Minutas de Visitas
- Anotaciones
- Estimaciones
- Estándares de Programación
- Diagramas de Entidad-Relación
- Entrevistas con Clientes
- Mapas de Navegación
- Procedimientos
- Flujos de Trabajo
- Etcétera...
Hay diez millones de cosas que podemos documentar. Existen estándares y procesos que nos indican qué deberiamos tener detallado y cómo. Sin embargo, el costo incurrido en tanta documentación debe encontrarse justificado por el beneficio que obtenemos al disponer de esa documentación. Digamos por ejemplo que decidimos comentar todo nuestro código. Si estamos en .NET usaremos los tags de <summary> y si estamos en java usaremos las herramientas que nos provee Javadoc para documentar código. Bien, después de unas buenas horas, hemos logrado colocar descripciones a todos nuestros métodos, parámetros, clases, campos y eventos. Estamos orgullosos y contentos de haber terminado con dicha tarea.
Al otro día le cae una tarea a Pepito que la resuelve sin problemas y sube su código al repositorio svn. Lo primero que notamos al actualizar nuestro working copy es que Pepito no puso ningún comentario a su código. Pues claro, otra cosa no se podía esperar. Juancito no le dijo a Pepito que de ahora en más se debe documentar todo el código, y mucho menos le dijo cómo. Entonces a Juancito se le ocurre escribir un estándar de cómo documentar el código, y lo envía a todos por e-mail, porque Juancito es rápido y organizado, y espera que los demás también lo sean. Pepito lee el documento, felizmente documenta su código y ahora sube esa nueva versión a svn. Juancito y Pepito estrechan sus manos y es otro gran éxito para el Jeropas Development Team.
Al cabo de dos días, a Juancito le piden que retoque lo que hizo Pepito, porque Pepito ahora está con algo nuevo. Muy bien dice Juancito, es la oportunidad perfecta para ver que nuestro estándar de cómo documentar el código rinda sus beneficios. Pero al cabo de media hora Juancito yace en el suelo convulsionando y delirando de fiebre. Encontró que los comentarios de Pepito eran de todo menos adecuados y legibles. La descripción de la clase Factura reza como sigue "Ese papel con tablas donde escribe Jorge los productos que se vendieron. Importante saber que está en pesos. Aguante Ferro loco."
Obviamente es un ejemplo exageradísimo, pero de nada sirve documentar si no lo hacemos concientemente. Es decir, debemos saber a quién va dirigida la documentación y luego hablar de una forma profesional y definida. Si un documento es para un cliente, no podemos hablar de entidades, tablas, procedimientos almacenados, vistas, clases, arquitecturas, componentes, etc (salvo claro que resulte ser un cliente con conocimientos técnicos suficientes). A un cliente le hablaremos con las palabras que conoce y que se desprenden de su glosario funcional: factura, remito, depósito, caja, configurar, pasar el lector, hacer click en el botón. No diremos que invocaremos el evento de lectura del código de barra, o que ejecutaremos una rutina X.
Esto es más que obvio, pero también porque dí un ejemplo muy obvio. Volvamos con nuestros amigos del Jeropas Development Team. Juancito ya volvió del hospital. Su médico le dijo que estará bien y le recomendó que no pretenda que todo le salga bien la primera vez. Consolado y descansado, Juancito encara a Pepito y al resto del equipo, y discuten un buen rato sobre qué se debería poner en cada summary. Llegando las 6 de la tarde, a Jorge Luis se le ocurre una gran idea que de paso le sirve para irse en horario:
Pongamos las cosas con definiciones técnicas como clase, contrato, interfaz, propiedad, tipo... Pero utilicemos las palabras que conoce el cliente, como facturar, imputar, depositar, extraer...Juancito lo piensa un momento y le gusta la idea. Ahora la clase factura podría decir "Clase que representa a un Comprobante que indica artículos y cantidades que serán procesadas e imputadas al cliente."
Mr Potato, el project leader del grupo, aprueba la idea con Juancito y finalmente están bien encaminados. Dos semanas después se encuentran con que Pepito tenía una clase con 54 propiedades, y todas estaban perfectamente documentadas. Pero los atributos internos también estaban documentados, y lo que hizo fué copy pastear lo mismo que puso en sus propiedades correspondientes. Entonces a Juancito se le ocurre que quizás están haciendo overkill, y están perdiendo tiempo en documentar absolutamente TODO. Una nueva reunión dá a lugar donde se decide no documentar los atributos (variables internas) ni las propiedades, salvo que estas no estén relacionadas a las columnas de la base de datos y sean realmente algo nuevo, como propiedades calculadas o propiedades de una clase de procesamiento, no de entidad de negocio.
Los chicos de JDT comienzan a trabajar de esa forma. Pronto encuentran que el entendimiento entre ellos mejoró mucho y Juancito está contento. Mr Potato vá con su superior, Mr Sarasa, y le dice que su equipo ha incrementado la producitivdad gracias a nuevas políticas de trabajo que se han aplicado. De esta forma, hace parecer que todo fué su idea. Sarasa lo felicita y le dice que continúe así, que llegará lejos. Potato se emociona y dice "vamos a explotar esto aún más". Arma otra reunión con Juancito donde terminan decidiendo que deberían documentar usando diagramas para indicar los requerimientos del cliente. De esta forma se pierde menos tiempo al explicar, dice Potato.
Juancito acepta y pronto crean su propio estándar para documentar requerimientos. Pero claro, ellos no los llaman requerimientos, porque pocos le dieron bola a los nombres de las cosas en la universidad. Ellos los separan en varios tipos: "Funcionalidades Nuevas", "Arreglo de Funcionalidades" y "Bugs". Definen y ponen la estética y el formato para tres templates de documentos que colgarán en la red y todos deberán utilizar para documentar los pedidos de los clientes. Al cabo de una semana la productividad del equipo baja increíblemente. "POTATO!!!" grita Sarasa desde su escritorio que flota en el aire, por encima de nuestras cabezas, y escupe un aire rabioso, como el de un dragón que respira sobre nuestras nucas. "¡Cómo es posible que ahora que documentan más, trabajan menos!". Potato, que no entiende un "SORONGOLIO" (estoy armando mi propio estándar de adjetivos, porque no le dí bola a la clase de lengua en la secundaria. Si ellos pueden, ¿por qué yo no?) no sabe qué decirle a Sarasa y termina echando la culpa sobre el pobre Juancito, quien es el que probablemente más se preocupa por estos temas.
Lo que ocurrió es evidente y lógico:
- No supieron distinguir entre los 3 tipos de "requerimientos".
- No pudieron comunicarse con los especialistas técnicos del cliente usando un lenguaje común.
- Tardaron más en documentar que hacer.
- A cada rato el cliente cambió o hizo agregados a los requerimientos, que los obligó a actualizar la documentación. Ahí se dieron cuenta que muchas cosas las tenían repitiéndose en varias partes del mismo documento.
- Cosas que pidieron los clientes tenían que hacerse enseguida y no podía esperarse 30 minutos para actualizar un documento interno.
- A causa de actualizaciones incompletas, los documentos empiezan a contradecirse.
- A causa de la mala documentación, el código creado no sirve contra la validación de un proceso de control VyV común.
- El cliente vé cambios como "Cambiar campo X de NVARCHAR(300) a NVARCHAR(MAX)" como un trabajo de 45 minutos, y se queja, ya que antes era una tarea de 5 minutos.
Y muchas otras cosas. Esto pasa cuando nos mandamos a hacer de nuestra empresa un mundo propio. Es como dije en el otro post, sobre la des-integración de aplicaciones. Creemos que nuestros problemas son únicos y no nos gastamos en investigar cómo se ha resuelto y cuales son las buenas prácticas utilizadas hoy en día.
No sean unos "SANGARENGONEINGOS" y denle una buena leída a todo el tema de documentación. Es muy útil pero "peligroso". Les recomiendo este artículo del gran Alex Papadimoulis: Documentation Done Right. Es una excelente lectura con una conclusión muy buena, y complementa perfectamente lo que quería poner en este post.
No sería sincero si les digo que este post de Alex no inspiró que haga uno propio, pero al menos creo que haber analizado las cosas de otro punto de vista.
Nos queda mucho por hablar sobre documentación. Apenas dí un ejemplo de una empresa que está empezando a aprender a documentar, empezó bien y pronto se encontró con mil problemas por la falta de proceso y verificación. Espero poder seguir abordando estos temas en los meses que viene.
Lo cierto es que actualmente me encuentro en una empresa que trabaja bien (aunque tiene sus cosas, como todas) pero no documenta casi nada. Empecé a implementar varias herramientas para documentar código (por algún lado debemos empezar, así que mejor empecemos por el código) así que aprovecho a comentar qué estoy usando:
- GhostDoc: Una herramienta que con un hotkey te autodocumenta métodos, eventos, propiedades, etcétera. Y podés customizar los mensajes que te dá y agregar los que faltan. Por ejemplo no tiene por default una descripción para las clases y las interfaces. Con su UI le agregué una y vá como piña. El problema es que por ahora no es muy multilenguaje que digamos. Hay configuraciones que uno puede encontrar en la web para autodocumentar en idiomas que no sean el inglés, pero GhostDoc tiene algunas cosas que no están abiertas al customizador. Por ejemplo el método GetFirstDocument() será autodocumentado como "Gets the first document". Pero un método ObtenerPrimerDocumento, por más que tengamos la configuración española, nos dirá "Obteners the primer documento". Es decir, el análisis sintáctico/semántico está atado al inglés hoy en día. Igual es una buena herramienta para probar, y si son fanáticos del inglés como yo, les vendrá joya.
- SandCastle: Esta excelente herramienta nos permite tomar todo nuestro código y auto generar documentación en varios formatos (web, help file, pdf) y podemos compartirla sin necesidad de tener el código. Nos crea una suerte de MSDN utilizando toda nuestra documentación XML. Ojo, su interfaz es nula, se maneja por comandos. Pero a continuación viene la solución a eso. Está bueno para usar de vez en cuando, y como la generación es automática, nos resulta barato.
- SandCastle Help File Builder: Nos brinda una interfaz simple para utilizar el poder de SandCastle.
- Enterprise Architect: Esto lo vengo usando hacer rato y no me canso. Es una herramienta inagotable, y lo digo en serio. Aún no le encuentro límites. Nos permite documentar lo que se nos ocurra. Centralizado primariamente en diagramas, podemos hacer todos los UML que nos plazca, aunque también posee diagramas de otro tipo como DFD, DER, etc. Recomendadísimo. Sirve para las diferentes etapas de un proyecto. Pero claro, recomiendo leer unos buenos libros de UML primero. También nos permite tomar todo nuestro proyecto y automáticamente crear los diagramas de clase. Y pronto estaré poniendo un thread sobre como auto generar los diagramas de secuencia usando el EA, que si bien no es tan straight forward, resulta muy útil.
Volviendo a la problemática de la documentación, la idea es que de a poco vaya cada empresa implementando PRACTICAS CONOCIDAS y adaptándolas a su propio contexto. Vemos que todas estas cosas derivan de un problema común global: Si no somos capaces de crecer como personas, las empresas no podrán crecer como tales. Se requiere de nuestra capacidad de aprendizaje e investigación para pasar de ser un quiosco a un almacen, luego a un supermercado, y finalmente a una multinacional. Y no nos olvidemos el eslabón final de toda empresa: Conquistar el mundo.
Oh sí.
