Documentar no es el problema. Posponer decisiones, sí.

Con los años dejé de ver la documentación de un Design System como un entregable. Empecé a verla como la forma de conservar el contexto detrás de las decisiones — para que el producto siga evolucionando aunque cambien las personas.

---

Durante mucho tiempo pensé que documentar un Design System era una tarea que podía esperar.

Cuando el proyecto iba justo de tiempo, siempre había algo más urgente: terminar componentes, corregir bugs, preparar una entrega o avanzar con nuevas funcionalidades. La documentación terminaba quedándose para “después”.

Con el tiempo entendí que el problema no era posponer documentación.

Era posponer decisiones.

Porque cuando una decisión no queda registrada, tarde o temprano alguien tiene que volver a tomarla. Y normalmente lo hace sin conocer el contexto original.

La IA no creó el problema, solo lo hizo evidente

Últimamente se habla mucho de Agentic Design Systems y de cómo la IA necesita documentación para entender un sistema.

Es cierto.

Pero creo que esa conversación empieza desde el lugar equivocado.

La documentación nunca fue importante porque la necesitara una inteligencia artificial. Siempre fue importante porque la necesitamos nosotros.

Lo que cambió es que ahora la IA nos obliga a enfrentar algo que antes podíamos ignorar: todas esas reglas que nunca escribimos porque “todo el equipo ya las conoce”.

Hasta que alguien nuevo llega. O alguien se va.

Y entonces descubrimos que muchas decisiones nunca estuvieron realmente documentadas. Solo estaban en la cabeza de alguien.

Un Design System nunca está terminado

Hay algo que me gusta recordar cada vez que trabajo con un Design System.

No es una librería. No son los componentes. No son los tokens. No es Figma. Ni siquiera es el código.

Todo eso son herramientas.

El verdadero Design System son las decisiones que viven detrás de cada una de ellas.

Y las decisiones cambian constantemente. Nuevos productos, nuevas necesidades del negocio, nuevas tecnologías… todo hace que el sistema evolucione.

Por eso nunca he visto un Design System “terminado”. Y, honestamente, creo que tampoco debería existir esa expectativa.

La documentación no tiene que ser perfecta

Hace poco leí una idea que me hizo mucho sentido:

La IA no necesita un Design System perfecto. Necesita uno honesto.

Mientras más lo pienso, más creo que eso también aplica para las personas.

Imagina que mañana llega un diseñador o un desarrollador senior a tu equipo. Tiene experiencia. Aprende rápido. Pero no conoce tu producto.

¿Cuánto podría entender únicamente leyendo la documentación?

Si necesita preguntar absolutamente todo, probablemente el problema no sea la persona nueva. Es que muchas decisiones nunca quedaron registradas.

No pasa nada si existen excepciones o inconsistencias. Todos los sistemas las tienen. Lo importante es conocerlas y hacerlas visibles.

Porque trabajar con un sistema imperfecto pero transparente siempre será mejor que trabajar con uno que aparenta estar completo.

Hoy documentar cuesta mucho menos

Durante años había una razón válida para no documentar. Era costoso. Difícil de mantener. Y muchas veces quedaba desactualizado pocas semanas después de escribirlo.

Pero eso también está cambiando.

Hoy existen herramientas capaces de generar documentación desde el código, sincronizar cambios automáticamente e incluso ayudar a construir documentación con apoyo de IA.

Eso no significa que el trabajo desaparezca. Significa que el esfuerzo ya no está en escribir todo desde cero.

Ahora podemos dedicar más tiempo a lo realmente importante: dejar claras las decisiones.

Al final, documentar es compartir conocimiento

Con los años cambié la forma en la que veo la documentación. Ya no la considero un entregable.

La veo como una conversación que el equipo deja disponible para quienes llegan después.

Es el lugar donde una decisión deja de depender de la memoria de una persona y pasa a formar parte del conocimiento colectivo.

Y quizá eso sea lo más valioso de un Design System. No los componentes. No los tokens. Ni siquiera las herramientas.

Sino la capacidad de conservar el contexto detrás de las decisiones para que el producto pueda seguir evolucionando, incluso cuando cambian las personas.

Porque al final, los sistemas cambian. La tecnología cambia. Los equipos cambian.

Pero las buenas decisiones merecen permanecer un poco más.

Creo que ese es el verdadero propósito de documentar. No llenar páginas. No cumplir un checklist. Sino asegurarnos de que el conocimiento pueda seguir creciendo sin depender de quién estuvo ahí para tomar la primera decisión.