Rédaction de prose
Ces règles s'appliquent à la documentation Markdown et aux commentaires de code, dans n'importe quel langage. Les règles marquées « Markdown uniquement » ne s'appliquent pas aux commentaires de code. Dans ces commentaires, on suit les conventions du langage, par exemple les liens de doc [Nom] en Go. Les compétences pour des types de documents particuliers (comme les ADR et les glossaires) ajoutent leurs propres règles par‑dessus celles-ci.
Ton
Décontracté mais précis. Écrivez comme un·e ingénieur·e expérimenté·e qui explique le sujet à un·e autre ingénieur·e. Évitez le langage de spécification trop formel. Préférez des explications claires et naturelles qui restent techniquement exactes. Le ton doit être accessible et conversationnel, mais pas familier.
Partez du principe que les lecteur·rices ont une compréhension intermédiaire du développement logiciel mais ne connaissent pas forcément les projets Dogmatiq ni le domaine du document. Évitez le jargon et expliquez les termes techniques nécessaires au document. Imaginez le·a lecteur·rice comme un·e développeur·se d'applications avec environ cinq ans d'expérience professionnelle, qui connaît Go mais a peu de connaissances en algorithmique ou en mathématiques.
Noms de fichiers (Markdown uniquement)
Utilisez des noms de fichiers en minuscules, comme glossary.md, sauf si une convention externe impose autre chose, comme LICENSE ou README.md.
Retour à la ligne (Markdown uniquement)
Reformatez chaque paragraphe pour que chaque ligne contienne le maximum de mots possible dans la limite de 80 caractères.
Ponctuation
- Utilisez des guillemets et apostrophes droits (
",') dans la prose, jamais de guillemets courbes. Les caractères non ASCII sont acceptables dans les blocs de code et les formules. - Écrivez les tirets cadratins avec un espace de chaque côté, comme dans
mot — mot. - Utilisez un tiret cadratin, pas des traits d'union, comme séparateur de parenthèse.
- Utilisez un tiret cadratin pour une apposition qui définit un terme, dans les listes et les paragraphes. N'utilisez pas de deux‑points, de point‑virgule ni de parenthèses pour cela.
- Envisagez de reformuler les phrases ou les paragraphes qui contiennent beaucoup de tirets cadratins.
- Utilisez les points‑virgules avec parcimonie, pour le contraste (A ; B ne fait pas), la qualification (A ; cependant B) ou la conséquence logique (A ; donc B). Préférez un point si les propositions se lisent naturellement comme deux phrases distinctes.
- Remplacez un double trait d'union (
--) dans la prose par un tiret cadratin le cas échéant. Sinon, suggérez la ponctuation correcte.
Orthographe
Utilisez l'anglais américain. En cas de doute, suivez go.dev, la documentation de la bibliothèque standard Go, ou les documentations AWS et GCP.
| US (correct) | Non US (incorrect) |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
Liens de référence (Markdown uniquement)
- Utilisez des liens de type référence, jamais des liens en ligne.
- Placez les définitions de liens en bas du fichier, dans des groupes commençant chacun par un commentaire HTML d'étiquetage, comme
<!-- references -->ou<!-- anchors -->. - Triez chaque groupe par ordre alphabétique du libellé. L'exception concerne les liens de version dans un
CHANGELOG.md, qui restent dans l'ordre croissant des versions :[0.9.0]vient avant[0.10.0]. - Lorsqu'un terme lié apparaît au pluriel, ajoutez une définition séparée pour le pluriel, par exemple
[instructions]: #instruction, pour que la source soit lisible naturellement. - Chaque définition doit être utilisée au moins une fois. Supprimez les définitions inutilisées.
- Chaque référence doit avoir une définition correspondante. Ne laissez pas de références cassées.
Relecture
Vérifiez le texte par rapport à chaque règle ci‑dessus. Pour chaque problème, citez le texte, nommez la règle qu'il enfreint et suggérez une correction.