Guide de Style de Documentation | EmDash CMS Everything

Ce guide définit comment la documentation EmDash est rédigée. Les contributions sont éditées pour y correspondre. Vous n’avez pas besoin de le mémoriser — les relecteurs et éditeurs aideront — mais le suivre fait qu’une contribution fusionne plus rapidement.

La documentation existe pour aider quelqu’un à faire quelque chose, puis à retourner à son projet. Écrivez pour un lecteur qui est fatigué, pressé, lit dans une deuxième langue ou est nouveau dans la pile technologique. Servez ce lecteur avant tout le reste.

Lisibilité

Privilégiez :

Des phrases courtes et des paragraphes courts.
Un vocabulaire simple plutôt que du jargon.
Les abréviations et acronymes écrits en entier la première fois.
Les titres et listes pour diviser les passages longs.
La voix active.

Documentez comment construire avec EmDash, pas comment EmDash est construit. Les détails d’implémentation appartiennent aux documents uniquement lorsqu’ils changent une décision que le lecteur doit prendre (quand choisir une valeur non par défaut, une mise en garde qui affecte son projet). Ils ne remplacent jamais un exemple d’utilisation.

Pour les sujets non-EmDash — TypeScript, le protocole AT, les polices web, SQL — créez un lien vers une source réputée au lieu de les expliquer. Documentez ce que quelqu’un doit savoir pour utiliser la fonctionnalité dans EmDash.

Ce qu’il faut souligner

L’accent d’une page doit être déterminé par ce dont le lecteur a besoin pour faire sa tâche, jamais par ce qui était intéressant ou récent pour les personnes qui ont construit EmDash. Trois habitudes à résister activement :

Pondération de l’auteur par récence. Qu’une décision soit nouvelle ou fraîche dans l’esprit de l’auteur n’est pas une raison pour la mettre en avant. Ce qui a le plus changé est rarement ce qui est le plus important pour un lecteur. Ordonnez les sections, les éléments de liste et les titres selon la fréquence à laquelle un lecteur en a besoin, pas selon quand ils ont été ajoutés. Si vous documentez quelque chose parce qu’il vient de changer, vous écrivez probablement une entrée de changelog, pas un document.
Saillance du constructeur sur saillance du lecteur. Les décisions d’architecture et de conception internes qui étaient significatives à prendre sont généralement invisibles et non pertinentes pour utiliser. Indiquez la capacité que le lecteur obtient, pas le mécanisme derrière. Un lecteur définissant une collection n’a pas besoin de savoir où le schéma est stocké, pas plus qu’il n’a besoin de connaître le langage de l’analyseur. Si le mécanisme aide vraiment quelqu’un travaillant sur EmDash, il appartient au document interne, pas à une page destinée à l’utilisateur.
Auto-définition par homme de paille. Ne définissez pas EmDash par contraste avec une caricature d’autres outils (“Contrairement à la plupart des CMS…”, “Les CMS traditionnels vous forcent à…”, “dans de nombreux CMS vous déclarez X dans le code”). Décrivez ce que fait EmDash, directement, et laissez-le se démarquer par lui-même. La comparaison n’est autorisée que lorsque la comparaison est la propre question du lecteur : sur la page d’évaluation et les pages d’orientation “Venant de…”. Même là, elle doit être spécifique et juste — des comportements et des compromis concrets, pas un homme de paille que le lecteur est invité à ne pas aimer.
Définition par négation. Formuler une capacité comme le travail que vous n’avez pas à faire — “pas de migration à écrire”, “pas de reconstruction”, “sans toucher au code”, “pas de service séparé” — est un homme de paille déguisé : cela ne fonctionne que pour un lecteur qui porte l’alternative que vous avez inventée pour lui. Indiquez ce que le lecteur fait et ce qui se passe. “Ajoutez un champ dans le panneau d’administration ; il prend effet immédiatement” — pas “ajoutez un champ sans migration, sans reconstruction, sans code”. L’exception est un comportement concret pertinent pour le lecteur exprimé positivement : “le contenu est servi à l’exécution, donc les modifications apparaissent immédiatement” est un fait sur EmDash ; “pas de reconstructions nécessaires” est le même fait formulé comme la douleur absente de quelqu’un d’autre — préférez le premier.

Le test pour toute phrase : un lecteur essayant de terminer sa tâche serait-il moins bien loti si elle était supprimée ? Sinon, supprimez-la. Si elle n’a de sens que pour un lecteur comparant EmDash à autre chose, elle est au mauvais endroit ou devrait être coupée.

Toujours actuel, pas de changelog

Les pages destinées aux utilisateurs décrivent comment EmDash fonctionne maintenant, pour un lecteur qui n’a aucune version antérieure en tête. Pas de “maintenant”, “plus”, “avant”, “au lieu de l’ancien”, “cela a changé”. Les différences de version à version ne vivent que dans un guide de mise à niveau. Qu’un concept ait été récemment introduit n’est jamais une raison de mentionner qu’il est récent.

Voix et ton

Écrivez des phrases neutres et factuelles. Énoncez les faits directement.

✅ Les plugins s’exécutent dans un environnement d’exécution isolé et ne peuvent accéder qu’aux API qu’ils déclarent.

❌ Les plugins vivent dans un petit bac à sable confortable où rien de mal ne peut jamais arriver !

N’utilisez pas nous, notre, nos ou allons-y. Vous n’êtes pas assis avec le lecteur. Reformulez pour vous adresser directement au lecteur ou décrire le système.
N’utilisez jamais je. La documentation ne parle pas de l’auteur.
Adressez-vous au lecteur comme vous si nécessaire, surtout pour signaler une étape où quelque chose peut mal tourner.
Ne narrez pas et ne racontez pas d’histoire. Pas de “maintenant que nous avons configuré X, passons à Y”. Commencez une section par l’objectif, puis les étapes.
Évitez la fantaisie, les mascottes et les références culturelles. Elles ajoutent de l’effort de lecture et ne se traduisent pas.
Les points d’exclamation sont rares. N’en utilisez un que pour quelque chose de vraiment encourageant ou surprenant. En cas de doute, utilisez un point.

Titres

Le titre de la page est le <h1> (du frontmatter title). Les sections commencent à <h2>.
Gardez les titres courts. <h2> et <h3> apparaissent dans la barre latérale “Sur cette page” ; prévisualisez-le et raccourcissez tout ce qui se replie.
Pas de ponctuation finale, y compris un deux-points.
Formatez le code comme <code> dans les titres de la même manière que dans le texte du corps.

Listes

Utilisez une liste à puces lorsque l’ordre n’a pas d’importance, comme un ensemble d’options ou de propriétés.
Utilisez une liste numérotée pour les étapes qui doivent être suivies dans l’ordre. Utilisez le composant <Steps> de Starlight pour les procédures.
Lorsque les éléments de la liste se développent en plusieurs paragraphes ou portent plusieurs termes de code, passez à des sections <h3> à la place.

Exemples

“par exemple” en entier introduit un seul exemple ou hypothétique.
“p. ex.” entre parenthèses introduit une liste non exhaustive (p. ex. GitHub, GitLab).
Une liste qui couvre toutes les options n’est pas une liste d’exemples — utilisez des parenthèses sans “p. ex.” (les propriétés requises (src, alt)).

Exemples de code

Les exemples de code sont aussi importants que la prose qui les entoure.

Introduisez chaque bloc de code avec une phrase complète et autonome sur sa propre ligne, indiquant au lecteur ce que fait le bloc. Ne commencez pas par un fragment de phrase se terminant par un deux-points, un titre nu ou “comme ceci :”.

✅ L’exemple suivant enregistre un plugin dans le tableau sandboxed :

❌ Ajoutez le plugin comme ceci :

L’introduction prépare le lecteur à ce que fait le code, donc il n’a qu’à comprendre comment. Elle crée également un modèle de remplissage de blancs pour un lecteur faisant quelque chose de légèrement différent.

Dans une procédure <Steps>, une instruction impérative directe est l’introduction (“Ajoutez un tsconfig.json :” suivi du fichier convient dans une étape numérotée).

Autres règles :

Utilisez du code réel et fonctionnel. Pas de foo/bar. Montrez une configuration réaliste, pas toutes les valeurs possibles — le lecteur n’en aura qu’une.
Ajoutez un nom de fichier title= à tout bloc qui représente un fichier, afin que le lecteur sache où va le code.
```
```ts title="src/plugin.ts"
```
Utilisez les annotations Expressive Code, pas les clôtures ```diff brutes, pour les changements avant/après. Marquez les lignes modifiées avec del={n} / ins={n} ou le texte modifié avec del="…" / ins="…". Gardez les diffs minimaux et locaux aux lignes qui changent.

L’exemple suivant montre une seule ligne qui change :
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
Prévisualisez le code rendu localement avant de soumettre. Une faute de frappe peut casser l’affichage.

Guides de mise à niveau et de migration

Un guide qui aide un lecteur à déplacer un projet existant vers une nouvelle version suit une structure fixe. Les sections “Que dois-je faire ?” sont la partie que les lecteurs apprécient le plus — n’économisez pas dessus.

Ouvrez avec : comment mettre à niveau, une note que les choses peuvent “juste fonctionner” mais continuez à lire sinon, et un lien vers le changelog.

Puis listez chaque changement cassant comme sa propre entrée :

### [Renamed/Changed/Removed/Deprecated]: <feature>

Dans les versions antérieures, <une phrase, passé, ce qu'il faisait>.

<Une phrase, présent, comment cela fonctionne maintenant>.

#### Que dois-je faire ?

<Actions impératives : Mettre à jour… / Remplacer… / Supprimer…, avec un diff minimal.>

Choisissez le verbe selon la façon dont le lecteur ressent l’impact. Si une nouvelle valeur par défaut remplace leur valeur, c’est un “Changed: default value”, pas un “Added: option”.

Un changement cassant est un changement qui nécessite une modification du projet du lecteur sinon il cesse de fonctionner. Donnez l’action, pas seulement le fait. Pas “la version minimale de Node.js est maintenant X” mais “vérifiez votre version de Node.js avec la commande suivante et mettez à niveau si elle est inférieure à X”.

Spécificités EmDash

Conventions pour les situations récurrentes, ordonnées par la fréquence à laquelle un contributeur les rencontre. Ceci est une liste de conventions, pas un classement des fonctionnalités qui comptent.

Plugins : sandboxed vs native

Les plugins sandboxed et native sont des formats différents avec des formes de création différentes. Un changement à l’un affecte rarement l’autre. Indiquez de quel format parle une page ou un exemple. Lors de l’édition d’une page de plugin sandboxed, ne modifiez pas les exemples de plugin native, et inversement.

Localisation

N’incluez pas les modifications de messages.po dans un PR de documentation. Un workflow extrait les catalogues lors de la fusion vers main. Les inclure crée de l’agitation et des conflits de fusion.

Fonctionnalités expérimentales

Une fonctionnalité derrière un drapeau expérimental, ou un format de fil instable sous un RFC, peut changer sans préavis. Gardez sa documentation légère, signalez-la avec un <Aside> de prudence et pointez vers le RFC ou la discussion comme source de vérité. Ne documentez pas une surface instable dans les moindres détails.

Comptes Atmosphere

Lorsque l’identité portable et détenue par l’utilisateur derrière Bluesky et le réseau AT Protocol plus large apparaît, appelez-la un compte Atmosphere et utilisez ce terme de manière cohérente. Liez la première mention au guide de connexion Atmosphere ou atmosphereaccount.com. did:plc:… et les handles sont ses identifiants concrets ; utilisez-les où une valeur littérale est nécessaire.

Les docs sont du code

Le site de documentation est un projet Astro adjacent à EmDash. Les modifications de documentation passent par le même flux de pull request et de revue que le code. Chaque modification de texte attend une revue ; une modification de formulation peut déplacer le sens d’une phrase ou nécessiter des modifications correspondantes ailleurs sur le site. De petits changements revus et cohérents gardent l’ensemble du site cohérent.