Rédaction

Ce guide s'applique à tout contenu textuel visible : interface d'admin, messages d'état, pages de docs/.

Deux contextes, deux voix

Interface (labels, messages, descriptions) : la plateforme rapporte ce qui s'est passé. Impersonnel, passif descriptif. L'utilisateur est le sujet implicite.

Documentation : on s'adresse directement au développeur qui lit. Phrases courtes, verbes actifs, ton direct.

Ce qu'on évite partout

Superlatifs et formules vides de premier plan, robuste, puissant, tout-en-un, intuitif, seamless

Le corporate notre plateforme vous permet de, dans une optique de, à cet effet

Chevilles inutiles Ainsi, En effet, Il convient de noter que, N'hésitez pas à, Veuillez noter que

Le tiret long dans une phrase Reformuler à la place : deux-points pour une explication, virgule pour une incise, point pour une phrase séparée. Le tiret reste admis comme marqueur de valeur absente dans une cellule de tableau.

La sur-promesse Si on ne peut pas le garantir, on ne l'écrit pas.

Interface

Voix

La plateforme rapporte. Elle ne dit pas « on a fait », elle dit ce qui s'est passé. Pas de « vous » ni de « nous ».

✓ « Les modifications ont été enregistrées. » ✓ « La page a été supprimée. » ✗ « On a enregistré vos modifications. » ✗ « Nous avons bien reçu votre demande. »

Labels et boutons

Courts, un verbe à l'infinitif, sans point final, sans majuscule à chaque mot.

✓ « Enregistrer », « Supprimer », « Ajouter une page » ✗ « Cliquez ici pour enregistrer vos modifications » ✗ « Ajouter Un Élément »

Messages d'erreur

Nommer ce qui ne va pas. Dire quoi faire si c'est utile. Pas de code technique si l'utilisateur n'est pas développeur.

✓ « Ce champ est requis. » ✓ « Ce slug est déjà utilisé. Choisir un autre. » ✗ « Une erreur s'est produite. Veuillez réessayer. »

Messages de confirmation

Une phrase, au passé passif, sans « avec succès ».

✓ « Page enregistrée. » ✓ « Élément supprimé. » ✗ « Vos modifications ont été enregistrées avec succès ! »

États vides

Expliquer la situation, pas seulement la constater. Ajouter l'action à faire quand elle existe.

✓ « Aucune page pour l'instant. Créer la première. » ✗ « Aucun résultat trouvé. »

Textes d'aide

Une phrase. Répondre à « pourquoi » ou à « comment », pas aux deux.

✓ « Utilisé dans l'URL. Ne peut pas être modifié après publication. » ✗ « Le slug est un identifiant unique utilisé pour générer l'URL de la page. Il doit être en minuscules et ne peut pas contenir d'espaces ou de caractères spéciaux. »

Documentation

Voix

On s'adresse directement au développeur. Verbes actifs, phrases courtes, sans intermédiaire.

✓ « Le registre permet d'ajouter des widgets sans toucher au core. Importer registerWidget et passer un composant. » ✗ « Le registre est un système centralisé qui permet la gestion modulaire des composants d'interface. »

Structure d'une page

• Frontmatter : title et description obligatoires. related.links quand la suite logique est évidente. Jamais de : dans une valeur non entourée de guillemets : YAML le lit comme une nouvelle clé et casse la synchronisation du site de documentation. Reformuler, ou entourer la valeur de guillemets.
• Titre : ce que le document permet de faire. Descriptif, jamais générique.
• Première phrase : pourquoi ce document existe, à qui il s'adresse.
• Prérequis si nécessaire.
• Corps : une idée par section, titres descriptifs.
• Notes : à la fin, pas au milieu.

✓ « Ajouter un widget à l'admin » ✗ « Configuration »

Exception : dans 03-reference/ et 06-modules/, où chaque section reprend le même découpage d'une page à l'autre, le titre est le nom court du sujet. C'est le dossier parent qui porte le contexte, le répéter dans chaque titre l'allonge sans rien apprendre. La description prend le relais pour dire de quel module il s'agit.

✓ « Installation », « Configuration », « Modèle de données », « API » ✗ « Installer le module Formulaires », « API du module Pages »

Le libellé d'un lien n'est pas tenu de reprendre le titre : à l'intérieur d'une section, il le reprend ; depuis une autre section, il peut redevenir descriptif pour garder son contexte.

Corps de texte

Phrases courtes, une idée par phrase, paragraphes de trois à quatre phrases au maximum.

Commencer par un constat ou une situation concrète, pas par une définition.

Pas de liste à puces pour des explications. Les listes servent aux étapes, aux options, aux éléments techniques.

Expliquer le pourquoi, pas seulement le quoi. Une contrainte technique sans sa raison sera contournée à la première occasion. C'est ce qui distingue une page de référence utile d'un simple listage de signatures.

Structure d'une page de référence

Uniforme sur toute la section 03-reference/ :

1. Une phrase : à quoi sert le module, quelle règle absolue s'applique.
2. ## Import : les sous-chemins exposés, et lesquels sont utilisables côté client.
3. ## API : un tableau signature, retour, description, puis un ### par fonction avec un exemple exécutable.
4. ## Variables d'environnement, le cas échéant.
5. ## Notes : pièges et frontières, à la fin.

Blocs de commandes

Une commande documentée se copie et s'exécute telle quelle dans bash, zsh et PowerShell, y compris PowerShell 5.1, celui que Windows livre par défaut. L'invite cmd.exe n'est pas une cible : elle ne connaît pas les commentaires #, que les blocs utilisent.

• Un argument en @scope se met entre guillemets doubles quand il contient un : ou qu'il est seul : "@lrvo:registry", "@lrvo". PowerShell lit sinon le @ comme son opérateur de splatting, et rejette la commande ou supprime l'argument. Un nom de paquet comme @lrvo/core passe sans guillemets.
• Une commande par ligne, pas de &&. PowerShell 5.1 le refuse. Un && reste admis dans un extrait de package.json#scripts : npm le confie à sh ou à cmd.exe, qui l'acceptent tous les deux.
• Guillemets doubles autour d'un argument, jamais simples. Les deux shells ne traitent pas l'apostrophe de la même façon.
• Pas d'utilitaire propre à Unix (grep, cat, cp, rm, heredoc) ni de variable posée devant la commande (VAR=valeur commande). Chercher d'abord l'équivalent que npm, node ou git fournissent partout : git grep plutôt que grep, le contenu d'un fichier montré dans son propre bloc plutôt qu'écrit par un heredoc.
• Sans forme commune, deux blocs : bash d'abord, powershell ensuite, chacun annoncé par une phrase.
• Un bloc de commandes ne contient que des commandes. Une ligne de .env ou de .npmrc collée dans un terminal est une erreur : elle va dans un bloc à part, précédé du nom du fichier.

Ces règles valent aussi pour une commande affichée par un CLI dans un message d'erreur ou une aide.

Captures d'écran

Les images vivent dans docs/assets/<section>/, en WebP, 1440 px de large au plus. Elles sont référencées en lien relatif, comme les pages :

![Le tableau de bord de l'admin](../assets/decouverte/tableau-de-bord.light.webp)

Une capture qui dépend du thème se livre en paire, <nom>.light.webp et <nom>.dark.webp. La page ne référence que la variante claire : le site de documentation ajoute la seconde balise tout seul, et le CSS n'en laisse qu'une visible selon le thème du lecteur. En lecture directe du dépôt ou de node_modules, seule la claire s'affiche. Une capture indépendante du thème se nomme sans suffixe et sert dans les deux.

Les dimensions sont lues au build, il n'y a rien à déclarer. Une image référencée mais absente de docs/assets/ fait échouer la synchronisation.

Ce qui se capture : une interface dont la forme d'ensemble porte l'information, un écran d'accueil de module, une interaction qui se décrit mal. Ce qui ne se capture pas : un formulaire champ par champ, déjà décrit par un tableau, et que la moindre évolution périme.

Chaque image part dans le paquet npm, donc sur le disque de chaque projet qui installe @lrvo/core. Compter 100 à 150 Ko par capture, et n'en ajouter aucune qui ne gagne pas sa place.

Liens

Toujours relatifs (../03-reference/01-cores/api.md), pour rester cliquables sur Gitea comme dans node_modules. Les related.links du frontmatter sont relatifs à docs/, sans extension.

Ce qui n'a pas sa place dans docs/

Le dossier docs/ a deux diffusions, et aucune n'est restreinte. Il est servi publiquement sur docs.lrvo.app, et build:docs le copie dans dist/docs/, donc sur le disque de chaque client. Il n'existe aucun mécanisme de publication sélective : une page déposée dans docs/ est publiée.

Une page de docs/ s'adresse donc au développeur qui intègre LRVO. Tout ce qui s'adresse au propriétaire va dans internal/, qui n'est ni servi, ni copié dans dist/, ni listé dans files : registre de risques, démarches juridiques ou administratives en attente, arbitrages commerciaux, faiblesses connues du dispositif de protection.

Le test : si la phrase décrit une chose à faire plutôt qu'une chose qui est, elle appartient à internal/.

Révision avant de livrer

• La première phrase dit déjà l'essentiel.
• Chaque phrase dit quelque chose. Les phrases qui meublent sont supprimées.
• L'interface utilise l'impersonnel. La doc s'adresse directement au lecteur.
• Le frontmatter porte title et description.
• Les liens relatifs pointent vers des fichiers qui existent.
• Chaque commande tourne dans bash, zsh et PowerShell.
• Les fautes sont corrigées.
• Le lecteur sait quoi faire ou quoi retenir après avoir lu.

Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, l'ajuster.