¿Por qué diseñar la documentación?
La documentación es un problema abierto en el diseño web. Hay patrones y antipatrones por todas partes, replicados hasta el infinito en plantillas prefabricadas. Las plantillas son rápidas y fáciles, pero tienden a meter el mapa conceptual de una aplicación concreta en un molde predefinido. Corren el riesgo de tratar la documentación como algo secundario que basta con embellecer dentro de cajas, en lugar de estructurarla como un modelo mental del producto para el usuario.
Además, las opciones de consenso suelen estar «sobrediseñadas», con efectos visuales que lastran la experiencia de lectura. Creemos que los sitios de documentación necesitan una experiencia de lectura más simple y centrada en el contenido, dejando los diseños más elaborados para el sitio de marketing (como ha comentado el creador de Fumadocs).
Pero en un mundo donde los agentes son la mayoría de los lectores de documentación (y también de sus creadores), ¿para qué diseñar siquiera tu sitio de documentación? ¿Merece la pena invertir esfuerzo en la legibilidad para personas y en el diseño visual?
Creemos que una interfaz de documentación intuitiva e intencionada cobra aún más importancia en el mundo de la morralla generada por IA. Esa convicción nace del aprecio por el oficio del diseño y de la obsesión por la experiencia de nuestro producto. Pero también nace de una observación: las personas siguen mirando y leyendo la documentación. Sí, los agentes son ejecutores masivos de código, pero las estadísticas de puro volumen no lo capturan todo. Las personas siguen visitando sitios de documentación para entender y evaluar un producto. Y cada vez necesitan más interfaces que despejen el ruido mental y dirijan su atención a lo importante.
Abordamos el rediseño de nuestra documentación desde cero, partiendo de los recorridos de usuario paralelos que exploramos en la reescritura de nuestro contenido. Solo existen unas pocas primitivas de documentación: navegación, búsqueda, controles, enlaces y contenido. Las dispusimos con menos líneas y más espacio abierto para lograr una experiencia visual más limpia, apoyándonos en el framework de documentación open-source Fumadocs para obtener la máxima capacidad de composición.
Trabajamos duro en nuestros textos y queremos que la gente los lea. El objetivo permanente es diseñar y mantener un sitio de documentación que haga que la lectura sea fluida e incluso placentera. Por el camino hemos desarrollado algunos principios de diseño fundamentales. El primero es adoptar una interfaz familiar y comprensible.
Flujo y dirección intuitivos
La documentación ayuda a los usuarios a construir un modelo mental del producto y de su funcionamiento, tal como contamos al hablar de la reescritura del contenido de nuestra documentación. Nuestro diseño partió de esos mismos principios fundamentales: una organización deliberada y con sentido, complejidad y personalización que se revelan de forma progresiva, y detalles discretos e incluso invisibles.
Cada área de la pantalla corresponde a una acción o salida unificada, de modo que las funciones se presentan a los usuarios allí donde esperan encontrarlas. (Como hemos comprobado que algunos usuarios tienen una marcada preferencia por los temas visuales, el selector de modo aparece en dos áreas).
Además, la página favorece un flujo intuitivo que encauza a los usuarios hacia lo que quieren lograr.
La documentación destaca enlaces a acciones que los usuarios podrían querer realizar, como consultar el Changelog para ver novedades, hacer una pregunta al equipo de soporte u obtener una demostración del producto.
Eliminar el desorden mental
Las interfaces están cada vez más recargadas. Elementos como el «antetítulo», animaciones aleatorias que se mueven en varias dimensiones y cajas superfluas (con esquinas redondeadas) son señales inequívocas de un diseño hecho con IA. La consecuencia de este desorden visual es un desorden mental que lo acompaña. Cuando cada componente existe porque sí, sin una ubicación pensada ni relación con los demás, el significado se diluye.
Así que nuestra primera tarea es reducir el desorden mental. Esto implica eliminar elementos superfluos; en nuestro caso, muchas líneas, enlaces y botones de más.
Pero también implica estructurar, reorganizar y simplificar de forma radical. En particular, consolidamos las superficies de navegación, entendidas como el mapa que organiza y señala los conceptos mentales del sitio.
Nuestra barra lateral es ahora un único acordeón. No suena revolucionario, pero se ha convertido en una rareza en los sitios de documentación, que a menudo muestran varias barras de navegación de sección en distintos lugares, tanto en vertical como en horizontal.
El CI impone una jerarquía clara en la barra lateral y evita que se convierta en una lista abrumadora de enlaces y opciones al mismo nivel. Y es persistente: hacer clic en un enlace no cambia por completo las opciones de la barra lateral ni te hace perder el hilo cuando intentas volver atrás.
Guiar la mirada
Un flujo intuitivo también le enseña al usuario a moverse por la interfaz. Queríamos dirigir la mirada del usuario de forma natural hacia las áreas importantes aplicando más jerarquía visual: en la navegación, los controles, el contenido y las acciones.
a) Usar iconos en las áreas importantes para romper los bloques de texto.
b) Añadir más separadores entre las secciones de texto para agrupar el contenido y hacer más evidentes las divisiones entre secciones.
c) Aplicar estilos de texto diferenciados, incluido el uso de cursivas (que la documentación suele evitar) y bajar el weight a 400 en el texto del cuerpo.
Sobre todo, queríamos crear mucho espacio en blanco para que el contenido respirara, inspirándonos en la documentación de Linear. El rediseño de la página de Quickstarts ilustra bien todos estos principios en conjunto.
Un toque distintivo de GT
Los sitios de documentación no dejan de ser páginas web, y no deberían resultar inertes. Con cuidado de no sobrediseñar ni restarle protagonismo al contenido, también añadimos detalles de «micro interfaz de usuario» para integrar nuestra documentación en la estética y el universo de la marca GT.
Creamos una interacción sutil sobre el icónico componente de tabla de contenidos de Fumadocs. Funciona con renderizado en el servidor como una máscara SVG, con un nivel de anidamiento de 12px y un indicador azul tenue que sigue al puntero. El panel deslizante en móvil dibuja la misma geometría de forma estática, ya que en pantallas táctiles no existe el hover.
Aplicamos la misma máscara a la barra lateral. Recorre una sección de arriba abajo y el indicador azul se desliza por el riel, curvándose hacia dentro allí donde el árbol se anida y siguiendo al puntero fila por fila.
También seleccionamos con cuidado otras primitivas de interfaz de usuario para contrarrestar los síntomas del diseño hecho con IA. Usamos únicamente iconos sólidos y menos redondeo en las cajas. Implementamos barras de desplazamiento coherentes en la barra lateral, los bloques de código y los menús, en lugar de la mezcla predeterminada de barras nativas y superpuestas. Y usamos SVG de banderas personalizados para nuestro selector de idioma en vez de emojis de banderas, para conservar una iconografía visual mate y mantener la coherencia con nuestra página principal.
Y, por supuesto, la experiencia de localización de nuestra documentación debe ser de primer nivel: conservando el espaciado, la alineación y el orden.
La lista negra
A lo largo del proceso, fuimos elaborando una “lista negra” de antipatrones que detectamos.
- Texto de antetítulo
- Texto explicativo innecesario y fuera de lugar
- Cajas demasiado redondeadas
- Iconos no sólidos
- Espaciado variable sin relación con la importancia del contenido
- Documentación sin localizar (!)
- Varios elementos de navegación repartidos por la página
- Barras laterales que parecen expandirse hasta el infinito
- Barras laterales que cambian al hacer clic en algo
- Barras laterales en las que pierdes de vista dónde estás
Por supuesto, seguimos trabajando sin descanso para mejorar el diseño de nuestra documentación y agradecemos cualquier comentario. ¡Feliz diseño de documentación!