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.

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s