Créer un site de documentation sans code : guide complet

Créer un site de documentation sans code

Listez vos pages avant d'ouvrir l'outil, décrivez l'arborescence dans le prompt, puis remplissez le contenu vous-même. Sur Zugo, une documentation est une plateforme multipage : 12 crédits pour les trois premières pages et 3 crédits par page ensuite. Une bonne documentation se juge sur la navigation, pas sur l'apparence.

Ce critère est plus exigeant qu'il n'y paraît. Un site vitrine réussi retient l'attention, une documentation réussie s'efface : le lecteur trouve sa réponse et repart. Tout ce qui ralentit ce trajet est un défaut, y compris les belles choses.

Qu'est-ce qui distingue une documentation d'un site vitrine ?

L'intention du lecteur. Sur un site vitrine, il découvre et se laisse convaincre. Sur une documentation, il arrive avec une question précise, souvent agacé, parfois en pleine panne de production. Il ne lit pas, il balaie.

Trois conséquences pratiques en découlent. Le sommaire doit être visible en permanence, parce qu'il sert de carte. Les titres doivent décrire une tâche (« connecter un domaine ») et non un objet (« domaines »), parce qu'on cherche une action. Et chaque page doit tenir sur un seul sujet, parce qu'une page qui traite trois choses n'est trouvable pour aucune.

Le découpage le plus utilisé dans le milieu, popularisé sous le nom de Diátaxis, sépare quatre familles de contenus. Elles ne s'écrivent pas de la même façon et ne se mélangent jamais sur une même page.

Mélanger explication et référence sur la même page est l'erreur la plus courante des documentations écrites par les auteurs du produit. Ils connaissent le pourquoi et le glissent partout.

Quelle arborescence tenir dès la première version ?

Une arborescence à deux niveaux, jamais trois. Un sommaire de premier niveau avec cinq à sept sections, et à l'intérieur des pages. Le troisième niveau donne l'illusion de l'ordre et fait disparaître les pages du champ de vision.

Commencez toujours par une page de démarrage rapide, même si elle vous semble trop simple. C'est la page la plus visitée de toutes les documentations, et celle dont dépend la première impression sur le produit. Elle doit mener à un résultat concret en moins de dix minutes de lecture.

Ajoutez ensuite les guides pratiques, dans l'ordre où les utilisateurs rencontrent les problèmes, pas dans l'ordre où vous avez développé les fonctionnalités. Ces deux ordres n'ont presque jamais de rapport, et c'est le vôtre qui perd toujours.

Gardez la référence pour la fin. Elle est longue, ennuyeuse à écrire et indispensable, mais elle ne sert qu'à ceux qui utilisent déjà le produit. La publier avant le démarrage rapide revient à donner un dictionnaire à quelqu'un qui cherche son chemin.

Quel prompt donne une base de documentation exploitable ?

Un prompt qui nomme le produit, le public, les sections et la mise en forme attendue. Les blocs de code et le sommaire fixe se demandent explicitement, sinon vous obtenez un blog.

Construis un site de documentation pour une API de facturation
destinée à des développeurs.
Structure :
- Sommaire fixe à gauche, visible sur toutes les pages,
  deux niveaux maximum.
- Section "Démarrage" : installation, première requête, authentification.
- Section "Guides" : créer une facture, gérer les relances, gérer
  les remboursements.
- Section "Référence" : liste des points d'entrée avec paramètres,
  présentés en tableaux.
- Chaque page commence par une phrase qui dit à qui elle s'adresse.
Mise en forme : blocs de code sur fond sombre avec bouton de copie,
police lisible, largeur de texte limitée pour la lecture.
Ton : neutre, phrases courtes, pas de vocabulaire marketing.

La contrainte de largeur de texte n'est pas cosmétique. Une ligne de code qui traverse un écran large devient illisible, et c'est le premier reproche fait aux documentations générées sans consigne. Zugo propose 25 modèles, et partir du plus proche évite de décrire une architecture à partir de rien.

Comment gérer la recherche et la navigation ?

Par la structure d'abord, par le champ de recherche ensuite. C'est l'inverse de l'intuition, et cela tient au fait qu'une recherche ne fonctionne bien que sur des pages correctement titrées.

Prévoyez trois chemins vers la même information : le sommaire latéral, les liens contextuels en fin de page (« étape suivante »), et la recherche. Un lecteur qui échoue par un chemin en essaie un autre avant d'abandonner. Une documentation qui n'offre qu'un seul chemin perd tous ceux qui l'empruntent mal.

Soignez les titres comme s'ils étaient des résultats de recherche, parce qu'ils le seront. « Erreur 401 lors de l'authentification » se retrouve, « Problèmes courants » ne se retrouve pas. Cette règle vaut aussi pour les moteurs externes, où une bonne documentation attire souvent plus de visiteurs que la page d'accueil du produit. Notre guide sur le référencement d'un site créé par IA détaille ce qui est produit automatiquement et ce qui reste à écrire.

Prévoyez enfin la page introuvable. Un lien de documentation circule longtemps, dans des tickets et des forums, et il finit par pointer vers une page déplacée. Une page d'erreur qui renvoie vers le sommaire sauve la visite.

Comment publier du code et des captures proprement ?

Les blocs de code se demandent dans le prompt avec leurs attributs : coloration, fond contrasté, bouton de copie. Sans bouton de copie, chaque lecteur sélectionne à la souris, et cette petite friction se paie en tickets de support quand une commande est mal recopiée.

Pour les captures d'écran, la règle la plus rentable est de les limiter. Chaque capture vieillit à la prochaine mise à jour de l'interface, et une documentation illustrée de captures périmées inspire moins confiance qu'une documentation sans image. Gardez-les pour les endroits où le texte échoue vraiment.

Numérotez les étapes des guides pratiques. Un lecteur interrompu par un collègue revient sur sa page et cherche où il en était : sans numéro, il recommence, et parfois il exécute deux fois une action qui ne doit pas l'être.

Enfin, écrivez les résultats attendus. « Vous devez voir un identifiant commençant par inv_ » permet à quelqu'un de savoir qu'il a réussi. Sans cette phrase, il continue sans certitude et découvre l'erreur trois étapes plus loin, là où elle est coûteuse à diagnostiquer.

Que faire des versions et des mises à jour ?

C'est le point où une documentation créée sans code montre ses limites, et autant le regarder en face.

Une documentation multiversion, où le lecteur bascule entre la version 1 et la version 2 du produit, se gère par duplication des pages concernées. Chaque page dupliquée est une page supplémentaire, donc 3 crédits, et surtout une page de plus à maintenir. Tant que vous n'avez pas de clients bloqués sur une ancienne version, ne créez pas cette complexité.

Pour la partie qui bouge le plus, séparez ce qui relève de la documentation et ce qui relève de l'annonce. Les nouveautés ont leur place dans un journal des modifications, les incidents dans une page d'état. Une documentation qui absorbe ces deux flux devient illisible en six mois.

Les mises à jour, elles, se font par modification : 3 crédits par retouche, ou 6 en mode Hi-Fi. Une documentation vivante consomme donc régulièrement, ce qui est normal, puisqu'une documentation figée est une documentation fausse.

Combien coûte une documentation de dix pages ?

Le calcul est simple. La plateforme démarre à 12 crédits pour les trois premières pages, puis chaque page supplémentaire coûte 3 crédits : une documentation de dix pages revient donc à trente-trois crédits, avant retouches.

Le plan Free donne 5 crédits, ce qui permet d'essayer mais pas de terminer ce projet. Pro coûte $25 par mois pour 200 crédits, soit environ 16 plateformes multipages ou 66 modifications, et Business $99 par mois pour 800 crédits. Pour une documentation qu'on met à jour chaque semaine, Pro couvre largement le rythme.

Côté temps, la génération d'une plateforme prend quelques minutes. La rédaction, elle, prend des jours, et c'est là que se joue la qualité du résultat. Aucun outil ne connaît le comportement exact de votre produit dans les cas limites.

Chaque construction est lancée dans un bac à sable avant livraison : une version qui ne s'ouvre pas ne vous est pas remise. En revanche, personne ne vérifiera qu'un exemple de code fonctionne réellement. Exécutez-les vous-même, un par un.

Où s'arrête un générateur sur une documentation technique ?

Il ne lit pas votre code source. Aucune référence ne se génère à partir de vos commentaires ou de votre schéma : ce que vous n'écrivez pas n'existe pas dans la documentation.

Il ne gère pas les contributions par branches. Un flux où plusieurs auteurs proposent des modifications relues avant publication demande un dépôt et un outillage. L'export GitHub permet de basculer vers cette organisation quand elle devient nécessaire, et le projet reste le vôtre.

La logique très spécifique se construit par retouches. Un sélecteur de version, un filtrage par rôle ou une documentation qui affiche des exemples dans plusieurs langages se gagnent en plusieurs modifications successives.

Zugo ne remplace pas une équipe de développement dès que la documentation devient un produit interne avec des dizaines de contributeurs.

Pour une équipe de deux à dix personnes qui veut publier vite une documentation claire, ces limites ne bloquent rien. Écrivez d'abord votre sommaire, puis le paragraphe qui décrit le produit, et regardez la première version sortir sur zugo.dev.