En casi todos mis proyectos hay una sección que me cuesta más escribir que el resto de la documentación: la lista de lo que todavía no funciona bien, o de lo que directamente no está hecho. No es la parte que apetece enseñar, pero es probablemente la más útil, tanto para mí dentro de un mes como para cualquiera que tenga que confiar en ese proyecto hoy.
Por qué molesta escribir limitaciones y por qué lo hago igual
Escribir una lista de limitaciones se parece a admitir en voz alta que el trabajo no está terminado. Es tentador dejarla para "cuando esté todo mejor" y mientras tanto no escribir nada. El problema es que ese momento en el que "todo está mejor" no llega nunca de golpe: los proyectos mejoran en pequeños incrementos, y sin una lista escrita, la memoria de qué falta se vuelve borrosa incluso para quien lo está construyendo.
Cuando retomo un proyecto después de dos semanas centrado en otra cosa, la lista de limitaciones me ahorra reconstruir mentalmente qué partes son sólidas y cuáles son parches temporales. Sin esa lista, tiendo a sobreestimar lo terminado que está algo, simplemente porque la última vez que lo miré funcionaba en el caso feliz.
Cómo la organizo en la práctica
Separo las limitaciones en tres tipos, porque no todas piden la misma reacción:
- Ausencias conocidas: funciones que directamente no existen todavía, como la pantalla para visitar el perfil de otro usuario mientras solo está lista la del perfil propio.
- Comportamientos parciales: partes que funcionan en el caso normal pero fallan o se comportan de forma distinta en casos concretos, como una función que depende de una conexión estable y no tiene aún un plan claro para cuando esa conexión falla.
- Decisiones pendientes: aspectos que dependen de una decisión que todavía no se ha tomado, no de trabajo técnico pendiente. Por ejemplo, cuestiones de nombre o de alcance de una función que se están evaluando.
Separar estos tres tipos evita mezclar "no lo he hecho" con "no he decidido si lo voy a hacer así", que son problemas distintos y que se resuelven de forma distinta.
Ejemplo práctico: el estado de un proyecto en curso
En los avances que publico sobre la app de mapa de pesca que estoy construyendo, siempre incluyo una sección de "estado a fecha X" con una lista corta y concreta: qué existe en el entorno de desarrollo, qué falta, qué sigue pendiente de decisión. Ahí digo, por ejemplo, que hay puntos privados, públicos y zonas aproximadas, pero que ciertas pantallas sociales todavía no están disponibles, o que una función de rutas tiene base técnica sin estar terminada de forma funcional.
Esa sección no es un aviso legal para cubrirme las espaldas. Es la referencia que uso yo mismo para decidir qué tocar primero la próxima vez que me sienta a trabajar en el proyecto.
Cómo evito que la lista se quede obsoleta
Una lista de limitaciones que no se actualiza es peor que no tener lista, porque genera una falsa sensación de estado actualizado. Para evitar esto, la reviso cada vez que cierro una función relevante: si algo pasa de "ausente" a "parcial" o de "parcial" a "resuelto", lo muevo en el mismo momento en el que hago el cambio de código, no en una revisión aparte al final de la semana.
También evito frases vagas como "en progreso" sin más contexto. Prefiero anotar qué falta exactamente para considerar algo resuelto, aunque sea una frase corta, porque "en progreso" no dice nada sobre si falta una hora de trabajo o un mes.
Cómo lo cuento a quien no lee el repositorio
La lista de limitaciones que uso internamente suele tener un lenguaje bastante técnico, pensado para ahorrarme tiempo a mí mismo. Pero cuando esa misma información llega a un avance público del proyecto, cambio el registro: en lugar de "endpoint sin paginación implementada", escribo algo como "por ahora la lista completa se carga de una vez, así que con muchos elementos podría notarse más lenta". Dice lo mismo, pero lo dice de forma que alguien sin conocimiento técnico entiende exactamente qué esperar y qué no.
Esta traducción no es un ejercicio de marketing suavizado, es simplemente adaptar el nivel de detalle a quién va a leerlo. La versión técnica y la versión pública deben describir la misma realidad, solo que con palabras distintas; si en algún momento dicen cosas distintas, es señal de que una de las dos está desactualizada y hay que corregirla antes de publicar nada más.
Errores que he cometido con esto
El error más frecuente ha sido escribir la limitación en el momento de detectarla y no volver a mirarla nunca más, dejando documentación que ya no corresponde con la realidad del código. El segundo error, más sutil, ha sido suavizar el lenguaje para que suene mejor: escribir "en fase de mejora" cuando lo honesto era "no funciona en este caso concreto". Ese suavizado no ayuda a nadie, y menos a mí mismo dentro de unas semanas.
Conclusión
Documentar limitaciones no es admitir fracaso, es dar información útil sobre en qué punto está realmente un proyecto. Prefiero una lista corta y actualizada a una memoria de lo bien que va todo. Esta misma disciplina es la que aplico cuando escribo qué significa trabajar con una regla de no regresión: documentar lo que falla es el primer paso para no volver a romperlo sin darme cuenta.