En el artículo anterior, te expuse algunas de las razones por las que los Ingenieros de Software solemos rehusarnos a documentar nuestro trabajo. También, remarqué un par de razones, que hacen importante la documentación en el software. Esta ocasión quiero continuar con una afirmación: la documentación es necesaria en el desarrollo de software. Los Ingenieros de Software debemos ser conscientes de que esta actividad es importante y no debemos omitirla.

En este texto desarrollaré tres ideas: por qué documentar, lo que no es documentación y cómo hacerlo.

¿Por qué hacemos documentación?

1. Documentamos para entender

En el software, las soluciones no vienen mágicamente a nuestra mente. Los ingenieros solemos hacer diversas actividades para entender el problema que queremos resolver, que incluyen bosquejar, diagramar, leer y anotar información. En los ambientes colaborativos es muy común el trabajar con diagramas y bosquejos en pizarras grandes, donde todos intervienen. Cuando queremos explicar algo, solemos valernos de instrumentos similares: un diagrama, un boceto, una representación de la solución, texto o, recientemente, un meme.

¿Qué hacemos cuando queremos aprender un framework o herramienta de desarrollo nuevo? Nos documentamos: miramos ejemplos y leemos la documentación que proveen. No lo niegues: sueles maldecir cuando ésta no es clara, legible y completa. ¿Empiezas a notar su importancia?

La documentación nos sirve para entender ideas y decisiones, así que vamos a la siguiente idea.

2. Documentamos para comunicar y ayudar

La mejor manera de comunicación, en el desarrollo de software, es el habla frente a frente. Sin embargo, esto no siempre es posible: no nos encontramos disponibles y no podemos ser omnipresentes, sobre todo en los casos donde hay que explicar o compartir la información con muchas personas a la vez, que están dispersas geográficamente.

Dejar plasmadas las decisiones y la información importantes ayuda a otras personas a entender y poder hacer algo con el sistema, como:

• Instalarlo y reinstalarlo en caso de necesidad
• Entender la gestión de la configuración (versiones y requerimientos técnicos necesarios)
• Comprender la arquitectura
• Replicar un ambiente de desarrollo o pruebas, paso a paso
• Dar mantenimiento correctivo y adaptativo, para saber dónde está cada parte
• Conectarse a tu API
• Un largo etcétera

Te recuerdo algo: el sistema no te pertenece, por lo tanto debes asegurarte que la información importante es comunicada, principalmente si no estás presente.

Lo que la documentación no es

Quizás en este punto estés pensando en decirme: Edgar, lo que dices es verdad, pero aún así documentar suele ser demasiado trabajo, pues hay que producir muchas páginas (a veces, obligados por un proceso).

Justamente, esa es la idea errónea de la documentación: pensar que se trata de abrir MS Words o Google Docs y empezar a teclear texto, o dibujar diagramas o seguir ciegamente un proceso solo porque así lo dicta. Eso no es la documentación, pues si incumple su propósito de comunicar y ayudar, es mejor no hacerla.

Documentar no es, pues, producir todos los diagramas UML que dicta RUP, o llenar religiosamente las plantillas de requerimientos, los reportes del plan, los manuales en PDF, etcétera. Documentar es plasmar información importante; a continuación te digo cuál y cómo hacerlo.

Qué y cómo documentar

Lo que siempre se debe documentar es la información que le es útil al equipo de desarrollo y a los stakeholders del software. Esto incluye:

• Perfiles de los usuarios
• Objetivos del cliente / usuario
• Información de la arquitectura
• Información para instalación y operación
• Información de usuario
• Requerimientos no funcionales (atributos de calidad)
• Preguntas, respuestas y soluciones a problemas comunes
• Información de interconexión
• Decisiones importantes sobre el sistema y su razón
• Lecciones aprendidas

Parece una gran cantidad de documentos, la realidad es que se traducirían en unas pocas páginas y diagramas; incluso, algunos de ellos son temporales. Lo ideal para la documentación permanente es utilizar herramientas que cumplan con estas características:

• Facilidad de edición
• Fácil acceso y distribución automática de la información
• Versionado automático

En mi experiencia, los sistemas Wiki cumplen todas estas características, además de facilitar la colaboración. En ocasiones, es suficiente con una pizarra para hacer los diagramas o los bosquejos de las ideas, dejarlos temporalmente a la vista y desecharlos o dejarlos en una herramienta permanente si siguen siendo necesarios. Lo importante es facilitar al equipo la creación de su documentación y darle mantenimiento.

Estas son algunas recomendaciones para plasmar tu documentación.

Combina elementos multimedia

Usa imágenes, diagramas, texto y audio o video donde sea posible. Algunos diagramas los comenzarás a mano, y solamente algunos serán registrados de forma permanente; ten mucho cuidado con las metodologías que prescriben la creación de TODOS los diagramas; en estos casos, realízalos a mano, valídalos y desecha los que no tienen utilidad permanente.

Limita el texto a unos dos o tres renglones descriptivos. Señala claramente, con negritas o títulos, la idea central.

Entiende a tu audiencia. Prueba cosas con el equipo, mantén lo que sirve y desecha el resto

Cada equipo y de desarrollo y grupo de stakeholders es diferente. Prueba diferentes elementos para ver cuáles comunican mejor las ideas con ellos y descarta los que no (aunque el proceso y la metodología obliguen a usarlos).

En mi experiencia, los equipos suelen comunicarse bien con post-its y pizarrones, y después integrar algunas de las cosas en un repositorio de información.

Integra el manual de usuario en el software…

El manual del usuario no tiene que ser un aburrido PDF o DOC con imágenes y texto, o un video costoso. ¿Te gusta programar? ¡Haz la información del usuario con código e inclúyelo dentro del mismo software!

Ahora, es común agregar estos elementos a los programas: tooltips, descripciones inline, texto que aparece automáticamente cuando una función se agregó, tours guiados en las pantallas, etcétera.

… y el de operación e instalación en código, scripts y documentos

Muchos deploys se pueden automatizar con scripts. ¿Adivina qué? los scripts también son documentación y ayudas mucho a los operadores con ellos.

Las funciones del software pueden documentarse en el código, claro que sí: los comentarios ayudan en esto; otra práctica es acordar nombrar los métodos, funciones y parámetros significativamente, para que quien los lea entienda qué está pasando allí sin la necesidad de recurrir a un manual.

Donde sea necesario, utiliza los comentarios para automatizar la generación de documentos HTML y PDF.

Usa estándares

Así como usarás cosas que funcionan para tu audiencia, debes mantener estándares. Conforme pasa el tiempo y los sistemas cambian, también lo hacen los equipos. Los nuevos integrantes o personas que tienen contacto con tu sistema deben ser capaces de comprender la información clara e ingenierilmente. Somos ingenieros, ¿recuerdas?

¿Qué te parecen estas ideas y recomendaciones? Si quieres saber más o discutir algunas, contáctame con toda confianza.

¡Nos vemos en la siguiente entrega!