El uso correcto de las plantillas...está en el contenido

Hola, de nuevo colaboro en el arranque de un proyecto, desde mi área de calidad. Y de nuevo, ayudo en la adaptación de las plantillas y procesos para que el proyecto se adapte a lo que el cliente necesita, cumpliendo al mismo tiempo los más altos estándares de calidad.

Acabo de recibir una felicitación porque el conjunto de plantillas y documentación para el proyecto, ha sido percibido por el cliente como excelente. Y sí, para no mentir, son las cosas que te llevas a casa tras un día de duro trabajo que te animan. Las cosas que te animan a seguir luchando por mejorar, por buscar la excelencia, por no apoltronarse sentados en la autocomplacencia.

Pero claro, como buen culo inquieto, quiero más. Y me pongo a pensar que efectivamente, las plantillas, con sus guías, ejemplos y bien pensada estructura, cubren todas las necesidades...¿o no? Pero...¿qué pasa con el contenido?

En algún momento,  todas esas plantillas se convertirán en documentación real, en contenidos que reflejen la realidad del proyecto en un cierto momento y sus objetivos, suposiciones y carencias. Y sin embargo, aquí es donde realmente empieza el valor aportado al cliente. Es como si al cliente le hubiéramos dado un puente. Y sí, el puente está bien. Pero el cliente no quiere un puente. Quiere cruzar el río. Del mismo modo, lo que necesita el cliente no es las plantillas. De hecho, no quiere ni la documentación. Sino el seguro, la garantía que proporciona el tener un adecuado control del proyecto.

La documentación me recuerda al seguro de la vivienda o del coche. Los programadores no quieren oir hablar de la documentación. Esto ya lo comentaba en mi artículo "Nos gusta programar, pero no documentar". Tampoco nadie quiere un seguro de coche o vivienda. Pero es algo necesario, ya que no podemos circular por ahí, sin convertirnos en "bombas en potencia". Del mismo modo, un proyecto sin adecuada documentación se convierte en una bomba en potencia, ya que ante el más mínimo problema, empezamos todos a correr como pollos sin cabeza, apagando el fuego como si fuéramos bomberos.

Y es importante recordar, que podemos ser muy buenos creando código super-optimizado, clases y estructuras de información super-funcionales y cumpliendo los más modernos estándares...Pero sin una adecuada documentación, no sirve. Eso me recuerda a los ofuscadores de código. Conozco  gente que no lo necesitaba: su código era auto-ofuscado.

En fin, espero que el equipo de los proyectos sigan trabajando bien, y sobre todo, documentando adecuadamente (evitando la "documentitis", por supuesto).

No borres tus huellas, vaquero

Esta entrada en mi blog la dedico a todos aquellos que borran sus huellas en el trabajo. Los que sólo guardan los ficheros en su última versión. Los que no versionan los documentos. Los que cuando tienen un fichero incompleto lo destruyen al comenzar uno nuevo.

Son los amigos de lo imperfecto. Tal vez sea la obsesión de aparentar perfección, o no mostrar debilidad, tan habitual en algunas empresas.

No se trata de guardar un registro de todo lo que hacemos, sino más bien de protegernos de nosotros mismos. Después de todo, la mayoría de herramientas de versionado de código nos protegen de nuestras ganas de cambiar el código en exceso, permitiéndonos recuperar una versión previa que funcionaba o que simplemente queremos revisar. Si estamos de acuerdo en el caso del código fuente...¿qué pasa con la documentación?

La documentación es parte del proyecto.

Debemos cuidar la documentación, tal y como hacemos con el código. De nada servirá esto a los que entienden que la documentación se hace "después del código".
Cómo me duele ver en los diseños técnicos o funcionales, código fuente o pantallas que se han obtenido de la versión final.
Los documentos  hay que versionarlos y cuidarlos como cualquier otro resultado de nuestro trabajo.

La necesidad del versionado.

Algunas ventajas de tener la documentación versionada en un repositorio:

• Documentación alineada con cada versión del código.
• Es fácil identificar los cambios en los objetivos, del mismo modo que el versionado del código permite identificar los cambios en los resultados.
• Acceso centralizado. Al estar la documentación versionada y centralizada, todo el mundo accede a la última versión.
• Notificaciones de versionado. Muchos repositorios de documentos avisan de nuevas versiones. Esto es útil porque el equipo de desarrollo puede estar informado de cualquier cambio en una Historia de Usuario, un Requisito (o como lo queráis llamar).
• Permite escalar proyectos. Es muy sencillo trabajar con post-its para documentar requisitos, pero escalarlo a un equipo de 50 personas en 10 países, no es sencillo. En un repositorio documental, incorporar a un nuevo equipo en otro país es tan simple como darles acceso.
• Utilizar un repositorio permite ahorrar reuniones: todo el mundo puede estar al tanto de que se está cociendo una nueva versión de los requisitos, o de que se han modificado 5 de las 10 historias de usuario de nuestro producto. Esto no significa que no sean útiles las reuniones. Simplemente se trata de que las herramientas hagan el trabajo más simple.

¿Y qué hacemos en un proyecto pequeño?

Si tu proyecto es muy pequeño, puedes hacer el versionado de forma manual. Guarda el archivo como "requisitos_v02" y ya está. También puedes integrar la documentación como parte del código, y que tu herramienta (Subversion, Git, etc), se encargue del resto.
De todas formas, es útil seguir con la documentación, las mismas técnicas que un repositorio de código:

• Check-out: Avisa de que el documento lo vas a modificar. Que la gente tenga claro que hay una nueva versión en curso. Eso les hará organizarse mejor y centrarse en las áreas que menos cambios vayan a tener. Pocas cosas molestan más que ver cómo llega un gran cambio sobre algo en lo que hemos dedicado varias semanas con sus larguísimas jornadas. Y más cuando hay otras tareas que podríamos haber avanzado en su lugar. Avisa de la fecha prevista para terminar la nueva versión.
• Check-in: Avisa de cada nueva versión. Que la herramienta (o tú mismo mediante un correo), notifique al equipo de una nueva versión de lo que sea (requisitos, análisis, etc). Hazlo ágil y simple. Tanto para el que lo lee, como para tí que lo escribes y que lo vas a tener que actualizar.

Actitud y respeto, fuentes del problema.

Al final, es una cuestión de respeto profesional, de velar por que nuestras acciones ayuden en lugar de interferir al resto del equipo. De intentar prever las consecuencias de nuestros actos, no limitarnos a soltar nuestro (llámalo código, documento o lo que sea), y darnos la vuelta para no ver los resultados.

Muchas veces oigo a la gente quejarse de lo mismo repetidas veces: "para qué documentar si nunca voy a tener la documentación actualizada". Es deprimente, ya que muestra un grave problema de actitud. Hazlo o no lo hagas, pero no lo intentes. Deja ya esa actitud derrotista, por favor. ¿Somos ágiles y por tanto capaces de abrazar los cambios en el código? ¿Y sin embargo no somos capaces de hacer lo propio con la documentación? Claro que van a llegar cambios, es algo inherente en el software. El problema está en que no documentamos, sino que escribimos novelas.

Yo no sé si hay falta de programadores, pero de lo que estoy seguro de que sobran novelistas, y faltan buenos analistas o arquitectos que documenten los objetivos técnicos y funcionales. Menos verborrea, y más UML, casos de uso, historias de usuario.

Plantillas...¿para qué sirven?

Escribo esta entrada tras observar una interesante actitud en nuestra profesión, aunque por otro lado no es nueva, sino que es tan antigua como dicha profesión. La verdad es que la tenía medio escrita hace ya días, y como llevo un buen lapso sin tener un minuto libre, creo que ya es el momento de sacar esta entrada a la luz.

Por un lado, desde el área de calidad yo preparo con cariño la metodología para cada proyecto:
- Adapto los procesos y herramientas.
- Adapto las plantillas al entorno, cliente, tecnología...
- Adapto el número de plantillas y procesos a cubrir al tamaño del proyecto y sus requerimientos de rigor, etc.
- Finalmente, intento detectar gaps que me indiquen que se trabaja más de la cuenta, y no se aporta valor al proyecto o a la empresa. El objetivo es hacer lo mínimo indispensable, y buscando siempre que nada se haga dos veces en dos sitios distintos.
- Luego con el día a día, compruebo si los proyectos necesitan algo (de más, o de menos).

Dicho esto, puedo encontrarme con la siguiente situación: para comunicar algo, alguien del proyecto manda un correo al cliente usando como adjunto un word en blanco (y unas frases escritas en él, sin ningún formato, logo ni orden prefijado).

Cuando lo reviso, realmente me pregunto porqué no se usó la plantilla que yo con tanto esfuerzo había preparado. Y no es porque me haya costado tiempo. En esta profesión, desde que se es programador, hay que aprender a que el trabajo (código o lo que sea) no es nuestro. No hay que tener el apego que se tiene a una obra de arte o a un hijo nuestro. Si hay que rehacerlo, o si hay que aplicar un cambio, se acepta. Eso no significa que lo hagamos con desgana ni sin cariño. Significa que hay que aceptar esos cambios igual que se acepta que un hijo tomará su propio rumbo lejos de nosotros algún día.

Volviendo al tema, a que si recibiéramos un documento de una empresa o del gobierno, nos gustaría que dicho documento no estuviera en blanco...sino que tuviera un formato...un logo identificando al organismo o empresa que nos lo envía...Sin embargo, cuando se trata de mandar al cliente un documento...¿porqué no usar una plantilla si ésta se encuentra ya disponible? ¿No da su uso una imagen de profesionalidad, coherencia y buen hacer?

¿No tiene el código su estilo, tabulaciones, estructura y formato? ¿Porqué no hacer lo mismo en lo único que va a ver el cliente (los documentos)? ¿No es cada día más común el usar patrones y estructuras de código estándares y que de esta forma nos aceleren el desarrollo?

Yo creo que el problema está en nuestra percepción de la diferencia entre el código y los documentos. El código lo vemos como algo que es para nosotros, y por eso le dedicamos más tiempo y atención. Sin embargo, la documentación nos es ajena: es algo para el jefe, o para el cliente.

Y aquí, en mi opinión, es cuando pecamos de no aplicarnos lo que exigimos a los demás. El código que nos pasan los compañeros nos gusta que esté estructurado y cumpla un estándar, si es posible, coherente y común en todo el proyecto. Pero no sentimos la misma obligación de seguir un estándar a la hora de por ejemplo usar un documento de cara al cliente.

Hay otro problema añadido con los documentos, y es que tienen la habilidad pasmosa de salirse de contexto. Un word adjunto a un correo, tiene sentido. Pero cuando alguien lo copia y pega en otro correo...o lo guarda en una carpeta de red...ya hemos perdido el contexto. Perdemos el autor, la fecha, la empresa...(oh, claro, tenemos las propiedades del documento, que ni son obvias ni fáciles de ver, aparte de que no demuestran un autor, sino la máquina desde la que se creó).

¿Y tú? ¿Eres de los que prefieres usar un documento en blanco aún cuando existan plantillas para algo? ¿O prefieres inventar la rueda una y otra vez excusándote en la creatividad?

Nos gusta programar pero no documentar



La documentación debe estar al servicio del proyecto y no al revés

Efectivamente, no nos gusta documentar. Esta afirmación llevo muchos años oyéndola, diciéndola y sufriéndola.

¿Porqué no nos gusta documentar?
Pues porque no nos proporciona ningún beneficio aparente. ¿Me cambia en algo la vida si documento 1, 2 o 700 páginas? Probablemente no.
Pero claro, esto es porque lo afirmamos mientras documentamos. Documentar no da el mismo tipo de satisfacción a los programadores que tirar líneas de código. ¿Qué pasa si dejamos pasar los años y tratamos de mantener un sistema sin documentación? Pueden pasar dos cosas:

• Yo mismo soy el autor del código, y dependeré de mi memoria. Esto apenas me ha pasado el 10% de las veces (el mantener mi propio código pasado mucho tiempo). Y mi memoria, sobre lo cual me considero una persona normalita, no es capaz de retener todas las decisiones funcionales y técnicas que dan lugar a cientos, miles de líneas de código en cada proyecto.
• El autor del código no está. Bajo mi experiencia, esto me ha pasado alrededor del 90% de las veces. Bien porque he cambiado de empresa y tengo que lidiar con las perlas de otros, o bien porque la persona que lo hizo o empezó ya no está, y ahora yo tengo que mantener lo suyo. En este caso, dependeré de lo bien que el autor o autores lo hayan comentado. Pero como veremos a continuación, tampoco será de utilidad.

Documentar el propio código, no me resolverá nada. Con suficiente tiempo, es posible deducir lo que hace el código. Eso es como decir que si tuviéramos el código de Windows, nos arreglaríamos los problemas que encontrásemos (no tengo otra cosa que hacer si tengo un error, que ponerme a mirar millones y millones de instrucciones, probando a ver qué pasó y cómo arreglarlo). Pero es que estamos dando por sentado que solo tocamos código para corregir cosas, que en nada afectan al resto del código.

Ahí está la clave: no se comenta el código para tener documentación, sino para acelerar los cambios en el código siempre que el objetivo del mismo ni sus circunstancias cambien. Si las circunstancias, la interrelación entre componentes, los requisitos, etc cambian...de poco me sirve el código ni sus comentarios.

Me hace mucha gracia quien afirma que la mejor documentación es el código. Me preocupa y me hace dudar de si esa persona ha mantenido proyectos grandes y antiguos. Las realidades de la empresa cambian, los programas y módulos con los que interactuamos cambian...los sistemas físicos en la empresa cambian. Tener que tirar del hilo del código y sus comentarios para tratar de deducir decisiones antiguas es agotador...e inútil. Porque es el pasado.

Hay quien afirma y afirmará que el código documentado lo es todo gracias a las habituales "balas de plata": patrones de diseño y arquitectura, buenas prácticas, estándares de desarrollo...Eso está muy bien para pequeños cambios y proyectos no muy antiguos. Pero la realidad es que todo eso ha cambiado en el tiempo. Lo que hoy nos parece la piedra filosofal, mañana estará obsoleto y habrá otros patrones, estándares, etc. Mantener código antiguo nos suele llevar a criticar a su autor, simplemente porque no entendemos las "balas de plata" de aquel momento (bueno, de acuerdo, a veces también hay código antiguo realmente horrendo).

Otro problema está en la dispersión y el tamaño. Está muy bien mantener código con comentarios de módulos pequeños, o sistemas concentrados. ¿Qué ocurre si mi código tiene millones de líneas de código, miles de módulos distribuidos en docenas de aplicaciones? ¿Qué ocurre si no tengo siquiera visibilidad de parte del código o de las aplicaciones porque son de otras empresas?

Aquí de nuevo entran en juego la documentación y los estándares. El primer punto a documentar es siempre las APIs o interfaces. Tanto si son nuestras como si no. Un fallo en el código no sabremos si es porque está mal implantada una API, si está con una versión obsoleta...a no ser que tengamos la documentación actualizada de esa API o interfaz. Los comentarios y la documentación, han de satisfacer objetivos diferentes.

Otra razón ineludible de documentar es la esencia misma de la orientación a objetos: abstracción, encapsulación, etc. Una capa de la arquitectura no puede saber de otra. Lo mismo las funciones o módulos. ¿Entonces cómo rastreo las decisiones que abarcan varios elementos si están dispersos y no saben unos de otros? ¿O es que tengo que hacer un "meta-comentario" (comentario de comentarios)? En realidad, esto que acabo de decir, no es ni más ni menos que la documentación que queremos evitar.

La mejor documentación, es la que está orientada a complementar al código y sus comentarios. Habitualmente, se hace a través de los entregables típicos:

• Requisitos. Recogen a alto nivel las necesidades del sistema desde el punto de vista de cliente/usuario. Son las necesidades básicas. Podemos de alguna forma asimilarlas a las historias de usuario a muy alto nivel. Deben aclarar el qué se espera.
• Análisis funcional: Contienen el qué debe hacerse para lograr lo que espera el cliente. Es suficiente con definir lo que la parte de la documentación de diseño técnico ha de desarrollar.
• Diseño técnico: Si se da trabajo a un programador, un diseño técnico puede contener la resolución a problemas técnicos que se han previsto (los comentarios en el código ya comentan los problemas imprevistos).

¿Estoy diciendo que estos entregables deben hacerse? No, para nada.
¿Tienen que ser 3? Pues tampoco. El hacer 1, 2 o 3 documentos dependerá del contexto. Incluso  un breve correo puede ser un análisis funcional de un pequeño cambio. Y no necesitas más. Dependerá de la metodología que se haya definido para el proyecto, el tamaño del mismo, la experiencia...

Lo que digo es que los anteriores son entregables típicos y satisfacen una necesidad. Pero una metodología que obliga de forma rígida (las que por desgracia se implantan en muchísimas empresas), son la causa de las críticas que hay hacia la documentación y hacia las propias metodologías. Si la metodología no se adapta a la realidad del proyecto, será un obstáculo, no un acelerador del trabajo.

¿Cuál es el límite? ¿Hasta dónde documentar? Eso, por desgracia, lo da la experiencia. Yo suelo dar en mis formaciones una máxima: si el analista técnico tiene dudas, es que el funcional necesita más. Si el programador no sabe qué hacer, seguramente el diseño técnico cojea.

Ojo: tampoco quiero decir que no contestemos a la persona que ha de continuar el trabajo. Yo por ejemplo, en un cliente, revisaba la documentación técnica con los programadores, y o bien modificaba el diseño técnico sobre la marcha, o directamente les indicaba cómo quería realizar las cosas, y ellos por un lado, y yo por el otro, seguíamos cada uno haciendo código/documentos. De hecho, algunos programadores terminaban llevando a cabo una solución ligeramente distinta: ellos después me explicaban el motivo, y yo adaptaba el documento a su realidad. Cuesta tiempo llegar a este nivel de colaboración, pero es un placer trabajar así. Das libertad a quien está a pie de teclado soltando código, y al final, lo importante, es que la documentación y el código no se descuadren, y que el equipo sienta que hay cierta libertad de hacer las cosas.

Y un apunte final: todo lo dicho aquí, sirve para cualquier ciclo de vida: cascada, iterativo, RUP, scrum, etc, etc. Siempre alguien tendrá que empezar a trabajar partiendo de algo que le habrán dado: un documento, una servilleta, un post-it en una pizarra...