Hay una frase que escuché mil veces en desarrollo:
El código debería explicarse solo.
Y sí, banco la idea.
Hasta cierto punto.
Porque una cosa es escribir código claro, con buenos nombres, responsabilidades separadas y sin hacer magia negra para sentirse crack. Eso está perfecto. De hecho, deberíamos apuntar a eso siempre.
Pero otra cosa muy distinta es usar esa frase como excusa para no documentar nada.
Ahí empieza el quilombo.
Sobre todo cuando hablamos de QA, automatización, flujos de negocio, ambientes, datos de prueba o criterios de validación. Ahí el código puede estar hermoso, pero no siempre alcanza.
El código te puede decir qué hace una función.
Pero no necesariamente te explica por qué ese flujo existe, qué riesgo cubre, qué datos necesitás, qué ambiente usar, qué endpoint es sensible o qué comportamiento ya fue hablado con negocio.
Y si esa información vive solo en la cabeza de alguien, no tenés conocimiento compartido.
Tenés dependencia humana disfrazada de agilidad.
Documentar parece pérdida de tiempo hasta que deja de serlo
Documentar da fiaca. No voy a hacerme el iluminado.
Sentarte a escribir un README, explicar cómo se corre una suite, dejar claro qué cubre cada prueba, anotar tags, datos de prueba, dependencias o errores conocidos no se siente tan productivo como automatizar diez casos más.
Pero después pasa lo de siempre:
- entra alguien nuevo al equipo,
- se rompe un test y nadie entiende por qué,
- QA necesita validar un flujo y no sabe qué datos usar,
- hay una regresión urgente y nadie sabe qué suite correr,
- cambió un endpoint y la documentación quedó en la prehistoria,
- alguien pregunta por quinta vez: “¿esto cómo se ejecutaba?”.
Y ahí el tiempo que supuestamente ahorraste no documentando te lo cobran con intereses.
Con intereses y puteadas.
Para QA, el contexto no es un lujo
QA no prueba botones.
QA necesita entender contexto, riesgo, negocio, ambientes, datos, dependencias y criterios de aceptación. Si no entendés eso, podés automatizar mucho y aun así estar validando cualquier cosa.
Por eso una documentación accesible y actualizada cambia bastante el laburo.
No hablo de escribir una novela en Confluence que nadie va a abrir nunca más. Hablo de documentación útil:
- qué hace el flujo,
- cómo se ejecuta,
- qué datos necesita,
- qué cubre y qué no cubre,
- qué dependencias tiene,
- qué errores conocidos existen,
- cómo interpretar un fallo,
- qué cosas no deberían tocarse sin avisar.
Eso ya es un montón.
Porque cuando QA tiene esa información a mano, deja de depender de perseguir gente por Slack o revolver tickets viejos como arqueólogo buscando una pista.
Clean Code no reemplaza documentación de proceso
Acá es donde para mí se mezcla todo.
Clean Code ayuda. Muchísimo.
Un test bien escrito debería ser entendible. Un Page Object no debería parecer un acertijo. Una función con buen nombre te ahorra comentarios pelotudos tipo // hace click en el botón arriba de un click().
Pero Clean Code no documenta decisiones de negocio.
No documenta acuerdos entre equipos.
No documenta por qué un flujo se valida de una forma y no de otra.
No documenta que cierto ambiente tiene datos raros.
No documenta que un servicio falla si le mandás determinado estado.
No documenta que producto aceptó una excepción porque el comportamiento viene de un legado que nadie quiere tocar todavía.
Y todo eso, en QA, importa.
Entonces sí: escribí código claro.
Pero no uses Clean Code como excusa para dejar al equipo sin mapa.
El código es parte del sistema.
La documentación también.
La documentación buena tiene que estar viva
El problema no es documentar.
El problema es documentar una vez, olvidarse y después fingir que eso sigue siendo verdad seis meses más tarde.
Eso es peor, porque una documentación vieja genera falsa confianza. Te hace creer que tenés un mapa, pero en realidad estás siguiendo una ruta que ya no existe.
Para mí, la documentación útil tiene que ser:
- Accesible: si hay que pedir permiso a tres personas para verla, ya arrancamos mal.
- Concreta: menos discurso y más información que ayude a laburar.
- Actualizada: si cambia el flujo, cambia la doc. Punto.
- Mantenible: si para actualizarla necesitás media ceremonia, nadie lo va a hacer.
- Cerca del trabajo real: README, notas del framework, documentación de suites, criterios de ejecución, lo que tenga sentido para el equipo.
No hace falta construir una biblioteca de Alejandría para cada feature.
Hace falta dejar lo suficiente para que el próximo no tenga que adivinar.
Documentar también te obliga a pensar mejor
Algo que me gusta de documentar es que te expone rápido cuando algo está flojo.
Si no podés explicar cómo se corre una suite, capaz la suite está mal pensada.
Si no podés describir qué cubre un grupo de tests, capaz automatizaste sin estrategia.
Si necesitás media hora de explicación oral para que alguien entienda un flujo, capaz el proceso depende demasiado de conocimiento tribal.
Y si todo depende de una persona, no tenés equipo.
Tenés cuello de botella.
Documentar molesta porque te obliga a ordenar.
Pero justamente por eso sirve.
El futuro te lo agradece
Para mí, documentar no es perder tiempo.
Es invertirlo.
Es dejar una base para que el equipo no tenga que redescubrir todo cada vez. Es ayudar al onboarding. Es bajar fricción. Es hacer que QA pueda trabajar con más autonomía. Es evitar preguntas repetidas. Es reducir dependencia de personas clave.
Y también es una forma de respeto por el que viene después.
Aunque muchas veces el que viene después seas vos mismo dentro de tres meses, mirando tu propio proyecto y pensando:
¿Qué carajo quise hacer acá?
Automatizar sin documentar puede parecer rápido al principio.
Pero si nadie entiende cómo mantenerlo, cómo ejecutarlo o qué valor aporta, tarde o temprano se vuelve deuda.
Y la deuda siempre se paga.
Así que sí: código limpio, nombres claros, buenas abstracciones y toda la bola.
Pero también documentación actualizada, accesible y pensada para el laburo real.
No para decorar.
No para cumplir.
Para que QA pueda laburar mejor y para que el equipo del futuro no tenga que putear al equipo del presente.