Aller au contenu

Pourquoi un site vitrine séparé de la documentation

Kirexo a deux sites publics : le site vitrine www.kirexo.app et cette documentation doc.kirexo.app. Les deux parlent du même logiciel, mais ils sont écrits, construits et publiés séparément. Cette page explique pourquoi on n'a pas fait un seul site, et ce que la séparation coûte. Les options, les marqueurs et les échecs possibles du build sont décrits dans la référence castor site:build.

Deux publics, deux questions

Le site vitrine s'adresse à des personnes qui ne sont pas techniciennes : une autrice, une association, une rédaction, une école. Leur question est pourquoi : pourquoi une plateforme de ce genre, pourquoi l'héberger soi-même, pourquoi l'étendre. Le site répond avec ces trois raisons, sans commande, sans extrait de code et sans nom de technologie. Une page fait exception : « Installer Kirexo », qui donne les quatre étapes minimales d'installation, commandes comprises (cf. Trois copies d'une même procédure). C'est la seule page à commandes du site.

La documentation s'adresse aux personnes qui installent, exploitent ou développent Kirexo. Elle suit le découpage Diátaxis (tutoriels, guides, référence, explications), qui suppose un lecteur prêt à lire une commande, une variable d'environnement ou une interface PHP.

Mettre les deux dans un même site aurait mélangé les registres. Soit la vitrine se serait remplie de détails techniques pour rester cohérente avec le reste du site, soit la documentation aurait hérité d'un ton de présentation qui n'a pas sa place dans une référence. Deux sites permettent à chacun de garder un seul public.

Deux natures, deux chaînes de build

La documentation est générée : mkdocs transforme les pages Markdown de docs/ en site HTML, avec son thème, sa navigation et sa recherche. Ce choix convient à plusieurs centaines de pages qui changent souvent et doivent rester reliées entre elles.

Le site vitrine est écrit à la main : cinq pages HTML dans site/, sans moteur de gabarits. La vitrine a besoin de ce que mkdocs ne donne pas facilement : le rendu exact du design system de Kirexo, une page qui reste entièrement lisible sans JavaScript et une politique de sécurité de contenu stricte (CSP). Pour cinq pages qui changent rarement, un générateur aurait ajouté une couche à configurer sans rien simplifier.

Le HTML écrit à la main a un défaut connu : certaines valeurs vieillissent sans que personne ne les relise (numéro de version, date de publication, empreinte mémoire, hébergeur, état des fonctions). Elles sont donc entourées de marqueurs kirexo:*, que castor site:build remplit à partir des sources du dépôt. Le reste de la page est copié tel quel. On garde ainsi la simplicité d'un fichier statique, sans laisser une valeur se périmer en silence.

Un seul design system, un seul pont

Séparer les sites ne veut pas dire séparer leur apparence. Le site vitrine utilise le design system de l'espace utilisateur de Kirexo : mêmes couleurs, mêmes polices, même sélecteur de thème clair, sombre ou système. Les fichiers du design system ne sont pas dupliqués dans site/ : le build les copie depuis le dépôt à chaque fois. Une correction de contraste apportée à l'application arrive donc aussi sur la vitrine au build suivant, sans qu'on ait à la reporter. Le choix de faire porter l'accent par le serveur et le thème par le visiteur est expliqué dans Pourquoi un accent d'instance piloté serveur.

La vitrine n'a que deux portes d'entrée vers la documentation, une par public qui passe du « pourquoi » au « comment » : « Vous développez ? Commencer ici », qui mène au tutoriel Écrire un plugin de diffusion, pour qui veut étendre Kirexo ; et le bloc « Aller plus loin » de la page « Installer Kirexo », qui mène au tutoriel Installer Kirexo chez soi, pour qui veut l'héberger. Les personnes qui veulent installer Kirexo suivent le tutoriel Installer Kirexo chez soi, dont le README.md livré avec chaque version est la copie hors ligne.

Trois copies d'une même procédure

La page « Installer Kirexo » (site/installer.html) est la seule entorse à la règle « une information vit à un seul endroit ». Les quatre étapes minimales d'installation y sont recopiées depuis la documentation, et elles existent une troisième fois dans install/README.md. Trois lecteurs, trois accès différents : le visiteur du site découvre et veut savoir si l'installation est à sa portée ; le lecteur de la documentation veut comprendre et aller plus loin ; la personne qui a téléchargé le bundle doit pouvoir installer hors ligne, sans ouvrir la documentation. Renvoyer les deux premiers vers une seule page aurait été possible. Le troisième, non : le README doit contenir la procédure, pas y renvoyer.

Un ordre, et un seul

Les trois copies ne sont pas égales :

  1. le tutoriel Installer Kirexo chez soi fait foi. Sa section « Installer en quatre étapes » est la référence ;
  2. la page du site en est un extrait : les mêmes quatre étapes, puis un bloc « Aller plus loin » qui renvoie vers ce tutoriel publié ;
  3. le README est aligné sur le tutoriel, au caractère près pour les commandes, tout en gardant sa propre structure.

Une modification commence toujours par le tutoriel et descend vers le site et le README dans la même MR, jamais l'inverse. La documentation fait foi parce que c'est elle qui approfondit : vérifier l'installation, inviter d'autres personnes, choisir l'entrée HTTP, sauvegarder, mettre à jour. Si la page du site faisait foi, chaque correction devrait remonter d'un extrait vers le texte complet, et rien ne garantirait que la suite du tutoriel reste cohérente avec ses premières étapes.

Ce que le garde-fou vérifie, et ce qu'il laisse à la relecture

Trois copies tenues par la vigilance divergent tôt ou tard, et c'est d'abord une commande qui diverge : la plus coûteuse des erreurs, puisqu'elle bloque l'installation. La cohérence est donc tenue par un contrôle automatique, branché dans castor site:check :

  • les titres des quatre étapes, identiques et dans le même ordre ;
  • les lignes de commande, identiques au caractère près (après normalisation des blancs) et dans le même ordre. Une commande « presque » identique, comme docker compose up -d à la place de docker compose up -d --wait, est un écart ;
  • le nombre d'étapes et de commandes, figé dans le contrôle : trois copies vidées ensemble ne passent pas pour cohérentes ;
  • le lien « Aller plus loin » de la page vers le tutoriel publié.

Le contrôle tourne sur chaque MR, y compris celles qui ne touchent que la documentation : c'est précisément là qu'une commande du tutoriel risque de changer sans que la page du site suive.

La prose, elle, reste une affaire de relecture. Elle est la même dans les trois copies, à deux différences près : le site retire les liens et garde leur texte en clair, et le README garde ses propres règles de forme. Comparer automatiquement des phrases qui diffèrent légitimement par leurs liens aurait produit un contrôle soit trop strict pour être tenu, soit trop lâche pour servir. On a préféré un verrou dur sur ce qui fait échouer une installation, les titres et les commandes, et une relecture sur le reste.

Un gestalt, pas un pas-à-pas

Les quatre étapes visent un administrateur qui connaît déjà Docker et Docker Compose : télécharger, configurer, démarrer, créer son compte. Elles ne contiennent ni lexique, ni vérification pas à pas, ni résultat attendu après chaque commande. La configuration repose sur .env.example, dont chaque variable est commentée, et docker compose config --quiet signale une valeur obligatoire oubliée. Une première version, en six étapes écrites pour un débutant, doublait la longueur de la page sans aider le lecteur réel, qui sait déjà lire un fichier Compose : ce qui ne sert pas à installer est renvoyé à la suite du tutoriel (vérification, comptes, sauvegarde, dépannage).

Le bloc des quatre étapes ne contient aucun encadré. Le cas le plus fréquent hors du chemin principal, un reverse proxy (Traefik, Caddy, Nginx…) qui occupe déjà les ports 80 et 443, tient dans la phrase de prérequis : faire les étapes 1 et 2, puis suivre un guide dédié avant l'étape 3.

Ce guide est Installer Kirexo derrière un reverse proxy. castor site:check ne suit pas les liens externes : il ne vérifie pas, à lui seul, que le lien du site vise une page qui existe.

Des statuts tenus à la main, mais surveillés

Le tableau « Où en est-on » de la vitrine indique ce qui fonctionne aujourd'hui et ce qui reste à faire. Sa source est site/data/statuts.json, tenu à la main. Une fonction y a un état parmi quatre : disponible, en cours, prévu ou pas prévu.

Le tableau n'est pas généré à partir du code, parce que les fonctions qu'il décrit (« écrire et programmer une publication », « tenir plusieurs carnets ») ne correspondent pas à une liste qu'on pourrait extraire du dépôt. Les décrire en langage courant reste un travail de rédaction.

Un fichier tenu à la main peut toutefois mentir, dans un sens comme dans l'autre. Le build vérifie donc ce qui peut l'être : chaque plugin réellement livré, c'est-à-dire déclaré dans config/bundles.php et rangé sous src/Plugin/<Nom>/, doit avoir une entrée « disponible » qui le cite. À l'inverse, une entrée ne peut citer qu'un plugin livré. Le site ne peut donc ni taire une extension disponible, ni en annoncer une qui n'existe pas encore. Le reste, en particulier la frontière entre « prévu » et « en cours », relève de la relecture. Les règles exactes sont dans le contrat de site/data/statuts.json.

Ce que la séparation coûte

  • Deux publications : la documentation et la vitrine ont chacune leur build et leur déploiement. La documentation part sur GitLab Pages par le job pages ; la vitrine part chez un hébergeur statique (deploybase, ou OVH en repli) par le job release:site-deploy, au même tag. La marche à suivre est dans Publier le site vitrine.
  • Une copie à surveiller : le petit script qui applique le thème avant le premier affichage est recopié dans chaque page de la vitrine. Comme la CSP n'autorise qu'une seule empreinte de script, le build échoue si une page s'écarte des autres.
  • Une procédure en trois exemplaires : les quatre étapes d'installation vivent dans le tutoriel, sur la page « Installer Kirexo » et dans install/README.md. Le contrôle de castor site:check tient les titres, les commandes et le lien « Aller plus loin » ; la prose reste à relire (cf. Trois copies d'une même procédure).
  • Une relecture humaine pour les statuts qui ne correspondent pas à un plugin, que le build ne peut pas vérifier.

Ce coût reste faible pour cinq pages, et c'est lui qui permet à chaque site de ne s'adresser qu'à son public.

Voir aussi