Más que papeles: por qué la documentación sigue siendo clave en QA (y cómo usarla bien).

La documentación es un componente esencial en los procesos de aseguramiento de calidad (QA) dentro del desarrollo de software y, en general, en cualquier desarrollo de producto o servicio. Su importancia radica en su capacidad para estructurar, organizar y preservar el conocimiento generado durante todas las etapas del proyecto, desde la planificación inicial hasta el mantenimiento del producto final.

¿No te ha pasado alguna vez que, al llegar a un proyecto ya empezado, el proceso de inicio es complejo? Y tú sin saber por dónde empezar y cómo realizar esos primeros pasos. Claro está que, aunque el inicio es siempre un reto, la documentación no solo se erige como imprescindible en ese momento, y también a lo largo de la vida del proyecto, con múltiples cambios que van surgiendo y ya no se sabe cuál es la fuente de la verdad.

Ventajas de la documentación en QA

Como hemos anticipado, algunas de las ventajas y puntos fuertes de tener una documentación en orden y al día son:

• Facilitar la comunicación. Actúa como un medio para transmitir información crítica sobre requisitos, diseño, arquitectura y decisiones técnicas entre los miembros del equipo. Esto reduce malentendidos y errores que luego cuesta mucho arreglar. Si has estado en algún equipo seguro que te ha pasado que, en momentos puntuales o incluso de seguido, unos equipos no se hablan con otros.
  
  Eso lleva a unas dinámicas horrorosas y de las que surgen multitud de problemas, no se entienden los requisitos funcionales, cada parte hace su trabajo pero no tienen la visión en conjunto… Al final, si nos ceñimos al mundo del software, se van creando silos entre los equipos, el conocimiento no fluye y cuando llegan los problemas (que llegarán), será un caos asegurado.
• Establecer estándares. Define criterios claros para pruebas, métricas de calidad y objetivos del proyecto. Esto asegura que todas las partes involucradas trabajen bajo parámetros comunes. Muchos de estos puntos tienen en común las dinámicas de los propios equipos y es que, en este caso, si hablamos de APIs y tenemos aunque sea un acuerdo sobre cómo hacer los endpoints, al final en la fase de integración habrá menos problemas.
  
  Imagínate que backend crea una url con los datos pero no con el formato estándar y, cuando llega el frontend para conectar todo, ven que el endpoint devuelve un 404. Pueden estar bastante tiempo pensando que hay algo raro y buscando una aguja en un pajar hasta que se den cuenta del detalle de la url.
• Garantizar continuidad. En caso de cambios en el equipo o rotación de personal, la documentación permite una transición fluida sin pérdida de información crítica. Un punto que, aunque es crítico, no se suele tener en cuenta.
  
  Esto puede ocurrir cuando la persona que tiene todo el conocimiento funcional y técnico de la aplicación se va (ya sea de proyecto, de empresa) y deja un vacío bastante grande donde nadie del equipo restante puede trabajar bien porque no conoce a fondo los detalles ni su implementación. En ese caso se producen multitud de errores de regresión.
• Adaptabilidad a largo plazo. Documentar requisitos funcionales y no funcionales facilita futuras modificaciones o escalabilidad del software sin necesidad de reconstruir desde cero.
• Minimiza retrabajos. Al documentar criterios de aceptación y casos de prueba, centrándonos en aspectos de calidad desde el inicio, se identifican errores antes de la implementación evitando fallos en producción que resulten costosos.
• Integración con terceros. Una documentación técnica bien estructurada permite que clientes, socios externos o perfiles de desarrollo adicionales trabajen eficientemente con el equipo interno, acelerando procesos como integraciones o revisiones.
  
  Esta tiene relación con uno de los ejemplos de las APIs y es que, cuando desarrollas elementos que van a usar terceros o un público general, debes tener mucho cuidado y poner mimo en la documentación que vayas a compartir. Una máxima de pruebas es que el usuario hará todo lo posible por romper la aplicación de maneras que nunca habrías pensado.

Y más concretamente para el apartado del aseguramiento de la calidad, la documentación adecuada aporta beneficios concretos al proceso:

• Reducción de errores. Al documentar casos de prueba y criterios de aceptación, se identifican problemas antes del lanzamiento, evitando fallos en la fase de producción.
• Optimización del tiempo. Una documentación clara ahorra tiempo al evitar esfuerzos duplicados y facilitar la solución rápida de problemas. Cuando se está en un proyecto bastante tiempo, los recuerdos se empiezan a entremezclar y ya no recuerdas claramente qué aspectos son antiguos requerimientos o los nuevos.
• Mejora en la calidad del software. Fomenta buenas prácticas al obligar a los equipos de desarrollo a estructurar su trabajo y pensar en soluciones sostenibles. En nuestra carrera como QA, va a haber momentos en los que tendremos que evangelizar a los equipos y, aunque se tarde un poco más de tiempo en entregar las tareas, recordar siempre tener los cambios actualizados en los documentos de referencia.
  
  Cabe recordar que, para medir la calidad, debemos tener unos indicadores acordes al proyecto en el que estemos ya que no es lo mismo una fábrica de metal que comercio electrónico o una red social. Hay que amoldar a cada producto o servicio las pruebas a realizar.

¿Cuáles son los inconvenientes?

Como siempre suele ocurrir en la vida, también el tener documentación puede llevar a tener ciertos desafíos que son complejos de resolver según las dinámicas en las que se encuentren los equipos.

• Exceso de documentación: genera desperdicio de tiempo y recursos si incluye información irrelevante o redundante.
• Falta de actualización: tener documentos desactualizados puede llevar a errores operativos y malentendidos. Algo peor que no tener documentación es tenerla desactualizada porque, a no ser que estés probando versiones anteriores del producto donde te sirva, estarás perdiendo tiempo y recursos leyendo y buscando para comprobar que el papel ya no es relevante para tu caso de prueba y tendrás que ir preguntando a las personas, gastando tiempo en reuniones y, por lo tanto, perdiendo eficacia en tu trabajo.
• Calidad insuficiente: una documentación incompleta o poco clara dificulta su utilidad práctica. Este punto es el típico del «quiero y no puedo» porque tenemos documentación que parece ser interesante pero en cuanto empiezas a rascar un poco la superficie, ves que está vacía y no contiene lo que necesitas.

Al final, la documentación suele ser una gran aliada no solo para nuestros procesos de calidad, además para todo el equipo. Pero cuando caemos en ciertos bucles, hay equipos que prefieren prescindir de ella porque los inconvenientes están superando con creces a las ventajas que esta aporta.

Tipos de documentación

Si nos centramos en un ámbito más centrado en la calidad, todo puede ser una fuente de información y documentación para nuestros compromisos.

• Casos de prueba. Detallan las condiciones bajo las cuales se evalúa el software. Normalmente, en proyectos ya empezados suele ser una fuente importante para tener el contexto de nuestro sistema bajo test.
• Requisitos funcionales y no funcionales. Especifican lo que el producto o servicio debe hacer y cómo debe comportarse bajo diferentes circunstancias.
• Actas de reuniones. Registran acuerdos importantes con clientes o stakeholders y suelen ser relevantes tanto a nivel histórico como a nivel de futuro, ya que podemos ver la evolución del producto o servicio y vislumbrar hacia qué lugar se quiere ir. Esto es una ventaja ya que nos proporciona un nivel agregado sobre riesgos futuros y podremos empezar a planificar y trazar ideas desde el minuto 0.
• Diagramas técnicos. Representan la arquitectura del sistema y sus componentes reutilizables. Si bien es una información bastante técnica, si se tiene los conocimientos necesarios es vital para las pruebas de caja blanca que se pudieran realizar.

Documentación y agilidad

Las metodologías ágiles han transformado tanto el enfoque como la forma de trabajar, haciendo que la documentación también tenga que evolucionar hacia un punto más eficiente. Como veremos ahora, en este enfoque se tiene más en cuenta la aportación de valor que la propia documentación.

• Se prioriza la creación de documentos que aporten valor real al producto.
• Se evita la generación excesiva de contenido detallado que requiera mantenimiento constante.
• Se fomenta un equilibrio entre interacción personal y documentación escrita para maximizar la productividad.

Si quieres más información, te remito a la guía de Scrum, un marco de trabajo ágil, donde puedes ampliar más información sobre el tema agilismo y la importancia de la documentación. Y, por supuesto al manifiesto ágil

Propósito de cada documento

Antes de realizar cualquier documentación debemos tener en cuenta algunas consideraciones, ya que de eso dependerá su éxito o su fracaso. No es lo mismo darle a una persona no técnica un documento con cientos de siglas y jerga técnica que no va a entender o darle quizás una vuelta de tuerca y suavizar o reformular ciertas partes, añadiendo también un glosario de términos que sí o sí deben ser plasmados en el documento.

Así que, antes de empezar a escribir, pregúntate y reflexiona sobre:

• ¿Quién es el público objetivo?

Perfiles de desarrollo, testers, stakeholders, usuarios finales, etc. Al igual que no usas los mismos términos y formas de hablar con un extraño, con la persona del banco o con tus amigos, hay que adecuarse al interlocutor que leerá el documento.

• ¿Qué información necesitan?

En inglés se utilizan las siglas TMI para decir que hay “demasiada información” y es que, dependiendo del ámbito en el que nos encontramos, tenemos que filtrar la información y dar la dosis justa para que se entienda.

• Evita tecnicismos innecesarios

Si debes usar términos técnicos, asegúrate de explicarlos o proporcionar un glosario.

• Sé directo/a

Usa frases cortas y evita rodeos. Por ejemplo, en lugar de decir que "es importante tener en cuenta que...", escribe "recuerda que...".

• Evita ambigüedades

Utiliza términos precisos para evitar interpretaciones erróneas.

• ¿Qué decisiones o acciones deben tomar con base en la documentación?

En resumen, la documentación es algo de suma importancia para el proceso de QA que puede llevar a un aumento cualitativo y cuantitativo de la calidad, pero también al resto del equipo. ¿Has tenido algún problema o te ha solucionado la documentación algo en tu día a día? Deja un comentario y te leemos.

Referencias

• La documentación: El secreto para optimizar procesos y evitar errores costosos
• La importancia de la documentación en el desarrollo de software
• Documentación recomendada en Testing para buena Gestión de calidad
• La Importancia de la Documentación en un Sistema de Gestión de Calidad
• Mejores prácticas para la gestión documental
• 10 mejores prácticas para un archivo eficiente en la gestión documental de tu entidad
• ¿Qué es la documentación de procesos? Guía práctica con ejemplos
• 8 mejores prácticas para garantizar la calidad de los datos en la empresa
• La importancia de la documentación en IT