Documentación de diseño que sí se mantiene: dueños, fuente única y automatización
La documentación de diseño se queda obsoleta cuando nadie la cuida. Cómo elegir una fuente única, nombrar dueños y automatizar lo que cambia y mantenerla.
¿Por qué se queda obsoleta?
La mayoría de la documentación de diseño no falla en el día uno. Falla después, cuando el equipo cambia un componente y nadie actualiza la página. LogRocket lo describe con una frase que conviene recordar: si la documentación se deja para el tiempo libre, nunca se hace (LogRocket, “Design system documentation”).
Estas son las causas más repetidas:
- Es una tarea secundaria. Se hace cuando sobra tiempo, y casi nunca sobra.
- Es de una sola persona o de un solo equipo. Si solo diseño es dueño, ingeniería y producto no la sienten suya.
- Está separada del producto real. Storybook advierte que una documentación que se aparta de los componentes engaña activamente a quien la lee.
- Vive en demasiadas herramientas. Cada copia es otro lugar donde puede quedar obsoleta.
- No tiene revisiones ni responsables. UXPin habla de “deuda de documentación”: contenido que ya no corresponde a lo que existe (UXPin, “Common design system documentation mistakes”).
¿Por qué le importa a un diseñador?
Porque la documentación es lo que tu trabajo deja cuando te cambias de proyecto. Si una decisión de diseño no está escrita, cada persona nueva la vuelve a discutir. Si está escrita pero desactualizada, la gente la sigue y se equivoca.
También es la herramienta que más reduce las preguntas repetidas. Las dudas que llegan una y otra vez en el handoff suelen tener respuesta en una página bien mantenida.
¿Cómo se mantiene viva?
Estas prácticas aparecen en LogRocket, Storybook y UXPin:
- Nombra dueños. Un equipo central o personas responsables por sección. LogRocket propone “documentation champions” con revisión de diseño, ingeniería, producto y redacción. UXPin asigna responsables por sección.
- Elige una fuente única de verdad. Decide dónde vive la información oficial. Storybook recomienda generar la documentación de componentes desde el código y enlazar en lugar de copiar.
- Automatiza lo que cambia. Props, ejemplos de tokens y variantes pueden generarse a partir de la fuente. Así las personas escriben lo que no se puede generar: la intención y el porqué.
- Define un ritmo. Revisiones periódicas, por ejemplo dentro de las ceremonias del sprint (UXPin), y auditorías de rutina (LogRocket). La cadencia importa más que la perfección.
- Versiona y registra cambios. Un changelog visible al inicio de la documentación muestra qué cambió y cuándo. LogRocket recomienda versionado semántico.
Storybook da un ejemplo de criterio de aceptación para el modelo de contribución: que el componente se use en tres o más lugares y que haya quién revise las propuestas. Así evitas documentar cada experimento.
¿Qué debe tener la documentación de un componente?
Lo esencial es esto:
- Uso y cuándo usarlo. Para qué sirve el componente (Storybook recomienda incluir cuándo usarlo).
- Cuándo no usarlo. Esta sección es la que más se olvida y la que más evita errores.
- Variantes, estados y props. Qué existe y qué se puede configurar.
- Ejemplos de correcto e incorrecto. Mejor en pares visuales lado a lado que en párrafos.
- Accesibilidad. Comportamiento con teclado, lectores de pantalla y contraste. Storybook pide documentar el comportamiento de accesibilidad.
- Tokens. Qué valores usa el componente y por qué. Storybook recomienda documentar la intención, no solo el valor.
Si el componente tiene reglas de redacción, como longitud de textos, muévelas a una sección aparte. Así la página del componente sigue siendo legible.
Ejemplo
Ejemplo ilustrativo: un equipo tiene tres páginas de documentación para el componente de botón: una en Notion, otra en Figma y otra en un documento de Google. Cada una dice cosas distintas sobre el tamaño mínimo. El equipo elige la fuente única en el código del componente, genera las props y las variantes desde ahí y deja en Figma solo un enlace. Nombra a una persona de diseño y a una de ingeniería como responsables, con revisión mensual. La primera vez que cambia el tamaño mínimo, el cambio se hace en un solo lugar y el changelog lo registra.
¿Cuándo NO conviene documentar todo?
- Cuando el componente cambia cada semana. Documentar algo en experimentación puede ser pérdida de tiempo. Espera a que se estabilice.
- Cuando nadie lo va a leer. Una página que no consulta nadie se queda vieja sin que nadie lo note. Revisa antes si la necesidad existe.
- Cuando la documentación sustituye a la conversación. Un documento no reemplaza a una persona que puede resolver una duda con dos mensajes.
Errores comunes
- Copiar el mismo contenido en tres herramientas.
- Escribir la documentación al final del proyecto, cuando ya nadie recuerda las decisiones.
- Tener un solo dueño y esperar que escriba todo.
- Documentar cómo se ve un componente sin documentar cuándo usarlo.
- No registrar los cambios, así que nadie sabe qué ha cambiado desde la última vez.
Cómo empezar mañana
Elige el componente que más preguntas genera en tu equipo. Escribe en una página cuatro cosas: para qué sirve, cuándo no usarlo, un ejemplo correcto y uno incorrecto. Decide dónde vivirá la versión oficial y pon un enlace desde el resto. Asigna un responsable y una fecha de revisión. Si el componente forma parte de un sistema de diseño, la contribución al design system te dará el proceso para incorporar cambios, y la colaboración con desarrollo te dirá qué información necesitan para implementarlo.