# 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. *Tags: ux, proceso, documentacion, sistemas, gestion* --- > [!info] Definición Rápida > La **documentación de diseño** es el registro escrito de cómo se usan los componentes, los estilos y los patrones de un producto, y por qué. Se mantiene viva cuando tiene un dueño, una fuente única de verdad y procesos que la actualizan junto con el producto. ## ¿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"](https://blog.logrocket.com/ux-design/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"](https://www.uxpin.com/studio/blog/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](/es/wiki/procesos/design-handoff/) suelen tener respuesta en una página bien mantenida. ## ¿Cómo se mantiene viva? Estas prácticas aparecen en LogRocket, Storybook y UXPin: 1. **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. 2. **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. 3. **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é. 4. **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. 5. **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](/es/wiki/conceptos/sistema-de-diseno/), la [[contribucion-al-design-system|contribución al design system]] te dará el proceso para incorporar cambios, y la [[trabajar-con-desarrolladores|colaboración con desarrollo]] te dirá qué información necesitan para implementarlo. ## Fuentes - [LogRocket: Design system documentation](https://blog.logrocket.com/ux-design/design-system-documentation/) - [Storybook: How to document your design system, best practices and tools](https://storybook.js.org/blog/how-to-document-your-design-system-best-practices-tools/) - [UXPin: Common design system documentation mistakes](https://www.uxpin.com/studio/blog/common-design-system-documentation-mistakes/) --- Source: https://www.fernandoux.com/es/wiki/procesos/documentacion-de-diseno/