Guide de style de la documentation

Ce guide définit comment la documentation EmDash est rédigée. Les contributions sont éditées pour s’y conformer. Vous n’avez pas besoin de le mémoriser — les relecteurs et éditeurs aideront — mais le suivre accélère la fusion d’une contribution.

La documentation existe pour aider quelqu’un à faire quelque chose, puis à retourner à son projet. Écrivez pour un lecteur fatigué, pressé, lisant dans une langue seconde ou nouveau dans la stack. Servez ce lecteur avant tout.

Lisibilité

Préférez :

• 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.
• Des titres et des listes pour aérer les longs passages.
• La voix active.

Documentez comment construire avec EmDash, pas comment EmDash est construit. Les détails d’implémentation n’appartiennent à la documentation que 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 liés à EmDash — TypeScript, l’AT Protocol, les polices web, SQL — faites 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.

Quoi mettre en avant

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

• Poids de la récence de rédaction. Le fait 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. L’élément le plus modifié est rarement 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 que ça vient de changer, vous écrivez probablement une entrée de changelog, pas de la documentation.

• Pertinence du constructeur plutôt que pertinence du lecteur. L’architecture interne et les décisions de conception qui étaient significatives à prendre sont généralement invisibles et non pertinentes à 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 du parser. Si le mécanisme aide véritablement quelqu’un travaillant sur EmDash, il appartient à la documentation interne, pas à une page orientée 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 beaucoup de CMS on déclare X dans le code »). Décrivez ce qu’EmDash fait, directement, et laissez-le parler de lui-même. La comparaison n’est permise 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 équitable — des comportements concrets et des compromis, pas un homme de paille que le lecteur est invité à rejeter.

• Définition par négation. Présenter une capacité comme le travail qu’on n’a pas à faire — « pas de migration à écrire », « pas de rebuild », « sans toucher au code », « pas de service séparé » — est un homme de paille déguisé : il 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 rebuild, sans code ». L’exception est un comportement concret, pertinent pour le lecteur, exprimé positivement : « le contenu est servi au moment de l’exécution, donc les modifications apparaissent immédiatement » est un fait sur EmDash ; « pas de rebuilds 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 en moins bonne posture si elle était supprimée ? Si non, 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.

Pérenne, pas changelog

Les pages orientées utilisateur décrivent comment EmDash fonctionne maintenant, pour un lecteur qui n’a aucune version antérieure en tête. Pas de « maintenant », « ne… plus », « autrefois », « au lieu de l’ancien », « ceci a changé ». Les différences entre versions n’existent que dans un guide de mise à niveau. Le fait 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 isolé et ne peuvent accéder qu’aux APIs qu’ils déclarent.

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

• N’utilisez pas nous, nos ou faisons. 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 concerne pas l’auteur.
• Adressez-vous au lecteur comme vous quand 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 véritablement 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 et raccourcissez tout ce qui déborde.
• Pas de ponctuation finale, y compris les deux-points.
• Formatez le code comme <code> dans les titres de la même façon que dans le corps du texte.

Listes

• Utilisez une liste à puces quand l’ordre n’a pas d’importance, comme pour un ensemble d’options ou de propriétés.
• Utilisez une liste numérotée pour les étapes qui doivent être suivies en séquence. Utilisez le composant <Steps> de Starlight pour les procédures.
• Quand les éléments de liste deviennent 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 chaque option n’est pas une liste d’exemples — utilisez des parenthèses sans « p. ex. » (les propriétés requises (src, alt)).

Captures d’écran

N’utilisez une capture d’écran que lorsqu’elle clarifie matériellement les relations spatiales, un état d’interface ou l’emplacement de contrôles. Gardez les instructions et autres informations essentielles dans le texte pour que la page reste utilisable sans l’image.

Chaque capture d’écran doit être actuelle et prise pour l’objectif spécifique de la page. Fournissez un texte alternatif qui décrit l’écran et l’état pertinents. Enregistrez le fixture, la route, le viewport, la langue et le thème pour qu’un autre contributeur puisse reproduire la capture.

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 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 le code fait, de sorte qu’il n’a qu’à comprendre comment. Elle crée aussi un modèle à compléter 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 chaque valeur possible — le lecteur n’en aura qu’une.

• Ajoutez un nom de fichier title= à tout bloc qui représente un fichier, pour que le lecteur sache où va le code.

  ```ts title="src/plugin.ts"

• Utilisez les annotations Expressive Code, pas des clôtures ```diff brutes, pour les changements avant/après. Marquez les lignes changées avec del={n} / ins={n} ou le texte changé avec del="…" / ins="…". Gardez les diffs minimaux et locaux aux lignes qui changent.

  L’exemple suivant montre un changement d’une seule ligne :

  ```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 coquille peut casser l’affichage.

Guides de mise à niveau et de migration

Un guide qui aide un lecteur à migrer 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 — ne lésinez pas dessus.

Ouvrez avec : comment mettre à niveau, une note indiquant que les choses peuvent « juste fonctionner » mais de continuer à lire sinon, et un lien vers le changelog.

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

### [Renommé/Modifié/Supprimé/Obsolète] : <fonctionnalité>

Dans les versions précédentes, <une phrase, passé, ce que ça faisait>.

<Une phrase, présent, comment ça 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 sa valeur, c’est un « Modifié : valeur par défaut », pas un « Ajouté : option ».

Un changement cassant est un changement qui requiert une modification du projet du lecteur sous peine de cessation de fonctionnement. Donnez l’action, pas juste le fait. Non 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 les plus importantes.

Plugins : sandboxed vs natifs

Les plugins sandboxed et natifs sont des formats différents avec des formes de création différentes. Un changement sur l’un affecte rarement l’autre. Indiquez quel format une page ou un exemple concerne. Quand vous éditez une page de plugin sandboxed, ne changez pas les exemples de plugins natifs, et inversement.

Localisation

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

Fonctionnalités expérimentales

Une fonctionnalité derrière un flag expérimental, ou un format wire instable sous un RFC, peut changer sans préavis. Gardez sa documentation légère, signalez-la avec un <Aside> d’avertissement, et pointez vers le RFC ou la discussion comme source de vérité. Ne documentez pas une surface instable en détail exhaustif.

Comptes Atmosphere

Quand l’identité portable, appartenant à l’utilisateur, derrière Bluesky et le réseau plus large du AT Protocol 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 quand une valeur littérale est nécessaire.

La documentation est du code

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