Le CLI était terminé. Trente commandes réparties en six catégories, auditées à travers six sessions indépendantes, chaque découverte Critique et Importante corrigée. Le code fonctionnait.
Mais du code qui fonctionne et que personne ne sait utiliser, c'est la même chose que du code qui n'existe pas.
La Phase 5 a traité la documentation comme un livrable produit, pas une réflexion après coup. Trois surfaces, quatre pages de documentation, cinq langues, une seule session. Voici comment nous l'avons abordé et pourquoi la stratégie de documentation compte autant que la stratégie d'implémentation.
Trois surfaces, trois audiences
La documentation CLI de sh0 vit dans trois endroits, chacun servant une audience différente :
1. La page marketing (sh0.dev/cli)
Audience : développeurs évaluant sh0 pour la première fois.
Objectif : montrer, ne pas raconter. La page marketing n'explique pas les flags de commande ou les codes d'erreur. Elle montre l'expérience terminal -- ce que le développeur tape et ce qu'il voit -- et fait une promesse : « Voici à quoi ressemble votre workflow de déploiement avec sh0. »
La section héro met en vedette sh0 push :
$ sh0 push
Pushing my-saas-app
Detected nodejs (Next.js) -- 92/100 health
156 files (4.7 MB) packaged
Uploading OK 1.2s
Building OK 45.8s
[ok] Live in 48.3s
-> https://my-saas-app.sh0.appSous le héro, un workflow en cinq étapes montre le cycle de développement complet : Initialiser, Pousser, Surveiller, Gérer, Ouvrir. Chaque étape est une commande, un extrait de terminal, une phrase expliquant ce qu'elle fait.
La section de référence des commandes regroupe les 31 commandes par catégorie avec des descriptions d'une ligne. Pas de flags, pas d'arguments, pas d'exemples. Juste assez pour répondre à « sh0 peut-il faire X ? » -- et un lien vers la documentation pour le comment.
2. La page du tableau de bord (/cli dans le tableau de bord sh0)
Audience : utilisateurs sh0 existants qui veulent utiliser le CLI.
Objectif : les rendre productifs en une page. La page CLI du tableau de bord suppose que le développeur comprend déjà les concepts de sh0 (applications, déploiements, domaines, projets). Elle se concentre sur les questions mécaniques : comment installer le CLI ? Comment s'authentifier ? Quelles commandes sont disponibles ?
La page s'ouvre avec le statut de connexion -- si le tableau de bord peut détecter un CLI en cours d'exécution. En dessous, la commande d'installation (curl -fsSL https://get.sh0.dev | bash), suivie d'une section d'authentification montrant sh0 login.
La référence des commandes est plus détaillée que la page marketing : elle inclut des icônes pour chaque catégorie, des descriptions brèves et la syntaxe exacte des commandes. Vingt-neuf commandes dans une liste parcourable.
La page entière est localisée en cinq langues : anglais, français, espagnol, portugais et swahili.
3. Les pages de documentation (sh0.dev/docs/cli/)
Audience : développeurs utilisant activement le CLI qui ont besoin de matériel de référence.
Objectif : complet, précis et consultable. Quatre pages couvrent l'intégralité du CLI :
| Page | Contenu |
|---|---|
| Vue d'ensemble | Architecture, workflows principaux, démarrage |
| Installation | Installation par plateforme, configuration, variables d'environnement |
| Push & Deploy | Référence complète de sh0 push, .sh0ignore, fichiers de lien, mode watch |
| Commandes | Référence complète des commandes avec tous les flags, arguments et exemples |
La page Commandes est la plus dense -- elle documente chaque flag de chaque commande, y compris les commandes des Phases 2-4 qui manquaient initialement dans la documentation.
Le problème de la dette documentaire
La Phase 5 a été exécutée deux fois. La première passe a eu lieu après la Phase 1, ne documentant que les commandes initiales : push, login, whoami et le CLI préexistant. Quand les Phases 2, 3 et 4 ont ajouté 15 nouvelles commandes, la documentation était immédiatement obsolète.
La seconde passe a mis à jour les cinq fichiers pour inclure chaque commande. Le diff était significatif :
| Surface | Avant (docs Phase 1) | Après (mise à jour Phase 5) |
|---|---|---|
| Commandes page marketing | 19 | 31 |
| Commandes tableau de bord | 14 | 29 |
| Workflows vue d'ensemble docs | 3 | 4 |
| Référence commandes docs | Partielle | Complète |
| Commandes non documentées | 10 | 0 |
Dix commandes -- init, link, open, config, watch, restart, stop, start, delete, domains -- étaient complètement non documentées entre les docs de la Phase 1 et la mise à jour de la Phase 5. Cinq autres étaient partiellement documentées (flags manquants ou descriptions incomplètes).
C'est le motif de la dette documentaire : chaque phase d'implémentation avance plus vite que la documentation ne peut suivre. La solution n'est pas de documenter de manière incrémentale (ce qui fragmente l'effort et risque l'incohérence) mais de regrouper les mises à jour de documentation et de les appliquer de manière exhaustive.
La stratégie i18n
La page CLI du tableau de bord est livrée en cinq langues. L'approche de traduction suit le motif i18n existant de sh0 : un objet TypeScript avec des clés de langue et des valeurs de chaîne, sélectionné selon la préférence de locale de l'utilisateur.
typescriptconst translations = {
en: {
title: "CLI",
subtitle: "Control your server from the terminal",
install_title: "Installation",
// ...
},
fr: {
title: "CLI",
subtitle: "Controlez votre serveur depuis le terminal",
install_title: "Installation",
// ...
},
// es, pt, sw
};Les noms de commandes et la sortie terminal ne sont pas traduits -- sh0 push est sh0 push dans toutes les langues. Seul le texte d'interface environnant (titres, descriptions, instructions) est localisé. C'est une décision délibérée : les outils CLI sont des artefacts intrinsèquement en anglais, et tenter de traduire la syntaxe des commandes crée de la confusion plutôt que de l'accessibilité.
Les cinq langues cibles reflètent le marché visé par sh0 : anglais (mondial), français (Afrique de l'Ouest et centrale), espagnol (secteur tech en croissance), portugais (Brésil, Afrique lusophone), swahili (Afrique de l'Est).
L'architecture de navigation
Ajouter une section CLI à la documentation a nécessité la mise à jour de la structure de navigation. Les docs de sh0 utilisent une configuration de navigation centralisée :
typescript// docs-navigation.ts
export const sections = [
{ title: "Getting Started", items: [...] },
{ title: "AI Assistant", items: [...] },
{ title: "CLI", items: [ // Nouvelle section
{ title: "Overview", href: "/docs/cli/overview" },
{ title: "Installation", href: "/docs/cli/installation" },
{ title: "Push & Deploy", href: "/docs/cli/push-deploy" },
{ title: "Commands", href: "/docs/cli/commands" },
]},
{ title: "API Reference", items: [...] },
// ...
];La section CLI se situe entre « AI Assistant » et « API Reference » dans la barre latérale. Ce positionnement est intentionnel : le CLI est un sujet plus avancé que l'assistant IA (qui ne nécessite aucune configuration) mais moins spécialisé que la référence API (qui s'adresse aux développeurs d'intégration).
La page d'index des docs a également reçu une carte CLI -- un point d'entrée visuel qui correspond au style des cartes existantes pour Getting Started, Deployments et les autres sections.
Ce que ressemble une bonne documentation CLI
Après avoir construit la documentation de 30 commandes sur trois surfaces, un motif a émergé sur ce qui rend la documentation CLI utile :
1. Montrer la sortie terminal, pas juste la commande.
Mauvais : « sh0 push déploie votre application. »
Bon :
``
$ sh0 push
Pushing my-app
Detected nodejs (Next.js) -- 85/100 health
42 files (2.3 MB) packaged
-> https://my-app.sh0.app
``
La sortie terminal dit au développeur à quoi s'attendre. La commande seule lui dit quoi taper.
2. Grouper par workflow, pas par alphabet.
Mauvais : config, cron, delete, deploy, domains, env, export...
Bon : Déployer (push, init, link, watch, deploy) -> Cycle de vie (restart, stop, start, delete) -> Config (login, whoami, config) -> Gestion (domains, env, logs, ssh)
L'ordre alphabétique est pour la référence. L'ordre par workflow est pour l'apprentissage.
3. Mettre les commandes dangereuses en dernier et les marquer.
La commande delete apparaît à la fin de la section Cycle de vie applicatif, avec des notes explicites sur l'exigence de confirmation. Les commandes destructives ne devraient jamais être la première chose qu'un développeur voit dans une catégorie.
4. Un exemple par commande, pas cinq.
La page Push & Deploy a des exemples détaillés pour sh0 push parce que c'est la commande principale. La commande restart a un seul exemple parce qu'un seul suffit. La profondeur de documentation devrait être proportionnelle à la complexité de la commande.
La vérification du build
Les deux bases de code ont été buildées après la mise à jour de la documentation :
bash# Site web
cd sh0-website && npm run build # Pass
# Tableau de bord
cd sh0-core/dashboard && npm run build # PassLes pages de documentation sont des composants Svelte, pas du markdown statique. Elles passent par le même processus de build que l'application. Un import cassé, une clé i18n mal assortie ou une erreur de syntaxe dans un bloc de code fera échouer le build.
C'est un avantage d'utiliser un framework de composants pour la documentation : le compilateur détecte les bugs de documentation.
Prochain dans la série : 16 commandes en un jour : l'histoire complète du CLI -- Comment nous sommes passés de « sh0 a besoin d'une commande push » à 16 nouvelles commandes, 2 endpoints serveur, 6 sessions d'audit et zéro bug connu -- en une seule journée.