Pourquoi concevoir une documentation ?
La documentation reste un problème ouvert du design web. On trouve partout des approches et des anti-patterns, répliquées à l'infini d'un modèle prêt à l'emploi à l'autre. Ces modèles sont rapides et faciles, mais ils tendent à faire entrer la carte conceptuelle d'une application donnée dans un moule préfabriqué. Ils risquent de traiter la documentation comme un détail de dernière minute, à enjoliver dans des encadrés, plutôt que comme une structure à bâtir : le modèle mental du produit pour l'utilisateur.
Par ailleurs, les options consensuelles sont souvent « sur-conçues », avec des effets visuels qui alourdissent l'expérience de lecture. Nous pensons que les sites de documentation ont besoin d'une expérience de lecture plus simple, centrée sur le contenu, et qu'il faut laisser les designs plus élaborés au site marketing (comme l'a expliqué le créateur de Fumadocs).
Mais dans un monde où les agents constituent la majorité des lecteurs de documentation — et aussi de ses auteurs —, pourquoi faudrait-il encore concevoir son site de documentation ? Faut-il même investir dans la lisibilité humaine et le design visuel ?
Nous croyons qu'une interface de documentation intuitive et réfléchie devient encore plus importante dans un monde saturé de contenus générés à la chaîne. Cette conviction naît de notre attachement à l'artisanat du design et de notre obsession pour l'expérience de notre produit. Mais elle naît aussi d'un constat : les humains regardent et lisent toujours la documentation. Oui, les agents exécutent du code en masse, mais les statistiques de pur volume ne disent pas tout. Les humains consultent encore les sites de documentation pour comprendre et évaluer un produit. Et ils ont de plus en plus besoin d'interfaces qui désencombrent l'esprit et guident leur attention vers l'essentiel.
Nous avons repris la refonte de notre documentation de zéro, en partant des parcours utilisateurs parallèles explorés lors de la réécriture de notre contenu. Il n'existe que quelques primitives de documentation : la navigation, la recherche, les contrôles, les liens et le contenu. Nous les avons agencées avec moins de lignes et plus d'espace pour une expérience visuelle plus épurée, en nous appuyant sur le framework de documentation open-source Fumadocs pour une composabilité maximale.
Nous travaillons dur sur nos textes, et nous voulons qu'ils soient lus. Notre objectif permanent : concevoir et maintenir un site de documentation qui rende la lecture fluide, et même agréable. Nous avons dégagé en chemin quelques principes de design fondamentaux. Le premier : adopter une interface familière et compréhensible.
Parcours intuitif et direction
La documentation aide les utilisateurs à se construire un modèle mental du produit et de son fonctionnement, comme nous l'avons expliqué à propos de la réécriture du contenu de notre documentation. Notre conception s'appuie sur les mêmes grands principes : une organisation réfléchie et pertinente, une complexité et une personnalisation dévoilées progressivement, et des détails discrets, voire invisibles.
Chaque zone de l'écran correspond à une action ou à un output unifié, si bien que les fonctions apparaissent là où les utilisateurs s'attendent à les trouver. (Comme nous avons constaté que certains utilisateurs ont une nette préférence pour les thèmes visuels, le sélecteur de mode apparaît à deux endroits.)
La page offre par ailleurs un parcours intuitif, qui guide les utilisateurs vers ce qu'ils cherchent à accomplir.
La documentation met en avant des liens vers les actions que les utilisateurs pourraient vouloir entreprendre : consulter le Changelog pour les mises à jour, poser une question au support ou demander une démonstration du produit.
Faire le ménage dans la surcharge mentale
Les interfaces sont de plus en plus encombrées. Des éléments comme le « surtitre », des animations aléatoires qui se déplacent dans tous les sens et des boîtes superflues (aux coins arrondis) trahissent une conception par IA. Cette surcharge visuelle s'accompagne inévitablement d'une surcharge mentale. Lorsque chaque composant existe pour lui-même, sans placement réfléchi ni relation avec les autres, le sens se dissout.
Notre premier travail consiste donc à réduire la surcharge mentale. Cela passe par la suppression des éléments superflus ; dans notre cas, beaucoup de lignes, de liens et de boutons en trop.
Mais cela passe aussi par la structuration, la réorganisation et une simplification radicale. Nous avons notamment regroupé les surfaces de navigation, cette carte qui organise les concepts du site et y renvoie.
Notre barre latérale se résume désormais à un seul et unique accordéon. Cela n'a rien de révolutionnaire en apparence, mais c'est devenu une rareté sur les sites de documentation, qui affichent souvent plusieurs barres de navigation de section à plusieurs endroits, aussi bien verticalement qu'horizontalement.
L'intégration continue impose une hiérarchie claire à la barre latérale, ce qui l'empêche de devenir une liste intimidante de liens et d'options placés tous au même niveau. Et elle persiste : cliquer sur un lien ne bouleverse pas ses options et ne vous fait pas perdre le fil lorsque vous souhaitez revenir en arrière.
Attirer le regard
Un parcours intuitif apprend aussi à l'utilisateur à naviguer dans l'interface. Nous voulions attirer naturellement son regard vers les zones importantes en instaurant davantage de hiérarchie visuelle : pour la navigation, les contrôles, le contenu et les actions.
a) Utiliser des icônes dans les zones importantes pour aérer les blocs de texte.
b) Ajouter davantage de séparateurs entre les sections de texte pour regrouper le contenu et rendre les divisions plus visibles.
c) Différencier les styles de texte, notamment en recourant à l'italique (que les documentations ont tendance à craindre) et en abaissant la graisse à 400 pour le corps de texte.
Nous tenions tout particulièrement à ménager beaucoup de blanc pour laisser respirer le contenu, en nous inspirant de la documentation de Linear. La refonte de la page Quickstarts illustre bien la mise en œuvre conjointe de ces principes.
Une touche GT bien à nous
Les sites de documentation restent des pages web, et rien n'oblige à ce qu'elles paraissent sans vie. Tout en veillant à ne pas surcharger le design ni détourner l'attention du contenu, nous avons ajouté des détails « micro-UI » pour inscrire notre documentation dans l'esthétique et l'univers de la marque GT.
Nous avons conçu une interaction discrète sur l'emblématique composant de table des matières de Fumadocs. Elle fonctionne avec le rendu côté serveur sous forme de masque SVG, avec un niveau d'imbrication de 12 px et un curseur bleu pâle qui suit le pointeur. Le tiroir mobile dessine la même géométrie de manière statique, le tactile n'ayant pas de survol.
Nous avons appliqué le même masque à la barre latérale. Parcourez une section de haut en bas et le curseur bleu glisse le long du rail, s'incurvant vers l'intérieur là où l'arborescence s'imbrique et suivant le pointeur ligne après ligne.
Nous avons également sélectionné d'autres primitives d'UI pour contrer les travers du design généré par IA. Nous n'utilisons que des icônes pleines et des arrondis plus discrets sur les cadres. Nous avons mis en place des barres de défilement cohérentes dans la barre latérale, les code blocks et les menus, au lieu du mélange par défaut de barres natives et en overlay. Et nous utilisons des SVG de drapeaux personnalisés pour notre language switcher plutôt que des emojis de drapeaux, afin de préserver une iconographie visuelle mate et de rester en accord avec notre page d'accueil.
Et bien sûr, l'expérience de localization de notre documentation se doit d'être irréprochable : préservation des espacements, des alignements et de l'ordre.
La liste noire
Tout au long du processus, nous avons dressé une « liste noire » des anti-patterns que nous avons repérés.
- Le texte de surtitre
- Le texte explicatif superflu placé au hasard
- Les cadres aux angles trop arrondis
- Les icônes non pleines
- Un espacement variable sans lien avec l'importance du contenu
- Une documentation non localisée (!)
- Plusieurs éléments de navigation éparpillés dans la page
- Des barres latérales qui semblent s'étendre à l'infini
- Des barres latérales qui changent dès qu'on clique quelque part
- Des barres latérales où l'on perd le fil
Nous travaillons bien sûr en continu à améliorer le design de notre documentation et tous vos retours sont les bienvenus. Bonne conception de documentation !