La documentation de Discourse est actuellement en cours de révision et d’édition pour s’aligner sur ce guide de style. Tous les sujets de documentation ne correspondent pas encore parfaitement à ce guide — nous y travaillons aussi rapidement que possible.
Ce document est considéré comme un document vivant qui guide la rédaction et la mise en forme de la documentation de Discourse. Ce sujet sera maintenu à jour selon les besoins. Si vous avez un doute concernant l’un des principes énoncés ici, veuillez publier un message dans ce sujet pour en discuter.
Le principe directeur de ce guide de style pour la documentation est de prendre en compte vos lecteurs et leurs besoins lors de la rédaction : que souhaitent-ils accomplir ? Quel est votre objectif en fournissant ce contenu ?
Liste de contrôle rapide lors de la mise en œuvre du guide de style :
- Le bloc métadonnées est présent et correct
- Le titre est orienté vers l’action
- Tous les titres utilisent la casse de phrase
- Les bons tags et catégories sont utilisés
- Le document est structuré de manière logique
Lorsque vous terminez un document, relisez-le pour vous assurer que tous ces critères sont remplis.
Veuillez prendre note de ces consignes de mise en forme du texte :
Informations métadonnées
- Le document doit appartenir à une et une seule des catégories suivantes :
- Utilisation de Discourse
- Guides généraux pour les utilisateurs non administrateurs
- Gestion du site
- Paramètres, plugins, contenu et administration générale du site
- Intégrations
- Guides pour l’intégration d’autres plateformes avec Discourse
- Clients hébergés
- Guides pertinents uniquement pour les clients hébergés
- Auto-hébergement
- Guides pertinents uniquement pour les sites auto-hébergés
- Guides pour développeurs
- Guides techniques pour le développement sur Discourse, y compris la création de thèmes, de composants de thème et de plugins
- Contribution
- Guides pour contribuer au projet open-source Discourse
- Utilisation de Discourse
- Le document doit appartenir à une et une seule des balises / types de document suivants :
#how-to#explanation#reference#tutorial
- Le document peut avoir d’autres balises applicables, avec un maximum absolu de 5 balises sur un seul document
Bloc métadonnées
Tous les documents doivent comporter un bloc en haut contenant une brève explication du sujet du document ainsi que toute information métadonnée pertinente supplémentaire, comme les niveaux d’accès requis pour l’utilisateur, si un accès à la console est nécessaire, ou tout autre élément. Ce bloc sera formaté sous forme de citation sans titre au-dessus. Voici un exemple de ce à quoi cela doit ressembler :
Ceci est un guide décrivant tous les paramètres cachés du site disponibles, comment les activer et pourquoi vous pourriez vouloir les modifier.
Niveau d’utilisateur requis : Administrateur
Accès à la console requis
Titres et en-têtes
- Rendez les titres du document orientés vers l’action
- Incorrect : « Comment activer les titres automatiques pour les fils de discussion »
- Correct : « Activer les titres automatiques pour les fils de discussion »
- Les titres de document ne doivent pas être trop longs
- Pour les sujets de type « comment faire », rendez le titre orienté vers l’objectif
- Tous les titres doivent être spécifiques et uniques
- N’utilisez pas de ponctuation ni de caractères spéciaux dans les titres de document, à l’exception des virgules
- N’incluez pas d’émojis dans les titres de document
- Utilisez la casse de phrase pour les titres et les en-têtes — cela signifie que seul le premier mot commence par une majuscule, ainsi que les noms propres et tout autre mot qui serait normalement capitalisé
- N’utilisez pas d’esperluette (&) dans les en-têtes, utilisez plutôt le mot complet (« et »)
Consignes générales d’écriture, ton et grammaire
- Utilisez la voix à la deuxième personne lorsque vous faites référence aux personnes lisant le document — c’est-à-dire utilisez « vous », pas « nous »
- Utilisez la voix active autant que possible
- Incorrect : « le bouton doit être cliqué »
- Correct : « cliquez sur le bouton »
- Définissez les acronymes et les abréviations lors de leur première utilisation ; si nécessaire, fournissez un lien externe offrant plus d’informations
- Utilisez des phrases courtes et aérez le texte en utilisant des paragraphes, des en-têtes et des listes plus courts
- Vous pouvez utiliser
**gras**et italique pour mettre en évidence des phrases ou des mots clés, mais n’en abusez pas - Évitez d’utiliser du jargon ou des termes techniques sans explications — en cas de doute, privilégiez l’explication
- Utilisez des captures d’écran lorsque vous décrivez une interface visuelle, telle qu’un élément d’interface utilisateur
- Ne documentez pas et ne tentez pas de révéler de futures fonctionnalités, produits ou services de Discourse, sauf autorisation explicite
- Utilisez des mots de transition tels que donc, bien que et de plus.
- Utilisez des contractions courantes : c’est, vous aurez, vous êtes, nous sommes, allons-y (traduction adaptée des contractions anglaises : it’s, you’ll, you’re, we’re, let’s)
- Inférez l’intemporalité dans la documentation — évitez les mots tels que bientôt, nouveau, maintenant, dernier, etc., qui deviennent rapidement obsolètes
- N’attribuez pas de qualités humaines au logiciel ou au matériel
- Par exemple : « Si vous passez un entier à cette API, elle se fâchera et lèvera une erreur »
- Par exemple : « Notre bot IA amical et ambitieux vous aidera à résoudre tous vos problèmes »
- Lorsque vous citez du texte (y compris depuis l’interface utilisateur de Discourse), utilisez des « guillemets »
- Lorsque vous citez une URL, utilisez des
accents graves(backticks) - Lorsqu’un exemple de domaine est utilisé, utilisez
discourse.example.com - Si cela est utile, vous pouvez utiliser des émojis au début d’un paragraphe pour le mettre en évidence. N’utilisez pas plus de deux ou trois de ceux-ci dans un seul sujet. Voici quelques exemples d’émojis que vous pouvez utiliser :
- - Une note informative
- Annonce ou avis
- Un message d’avertissement
- Information très importante
- Évitez :
- Les métaphores ou l’humour inutiles
- Les références culturelles et régionales
- De dicter ou d’ordonner des procédures sur un ton condescendant — par exemple, Vous devez cliquer sur Publier ou Vous devez cliquer sur Publier
- D’être trop poli. Par exemple, Veuillez cliquer sur Publier
- D’utiliser des points d’exclamation sauf en cas de besoin absolu
- De mettre des mots en majuscules inutilement
- L’utilisation excessive des mêmes phrases et pronoms
Pour la documentation destinée aux utilisateurs finaux :
Maintenez un ton amical et informel, en mettant l’accent sur la clarté et la concision de manière knowledgeable. Allez droit au but rapidement. Expliquez les termes techniques, mais veillez à ne pas être condescendant. Pour assurer la clarté, commencez par préciser brièvement le contexte du sujet actuel.
Pour la documentation destinée aux développeurs et technique :
Maintenez un ton direct et précis. Utilisez le même ton que pour la documentation utilisateur, mais vous pouvez supposer un niveau de connaissances techniques plus élevé chez vos lecteurs.
Structure
- Allez droit au but rapidement — commencez par ce qui est le plus important
- Incluez les mots-clés importants tôt dans le document
- Rendez les choix du lecteur et les prochaines étapes évidents
- Utilisez toujours un balisage léger pour rédiger la documentation (Ceci est déjà intégré dans Discourse avec Markdown-it).
- Référence d’utilisation : https://markdown-it.github.io/
- Organisez votre documentation dans un flux logique — commencez par un aperçu, suivi de sections détaillées, et d’un résumé ou d’une conclusion si applicable
- Utilisez des en-têtes et sous-en-têtes pour structurer votre contenu, facilitant ainsi la lecture rapide et la recherche d’informations spécifiques — utilisez une hiérarchie décroissante dans les en-têtes, en commençant par h2, et ne sautez pas de niveaux
- Fournissez des liens vers des sujets ou des sections connexes dans votre documentation — cela aide les utilisateurs à trouver des informations supplémentaires sans recherches inutiles
Liens
- Utilisez un texte significatif dans les liens
- Sauf si le format de l’URL est important ou instructif, n’utilisez pas une URL comme texte de lien — utilisez plutôt le titre de la page ou une description de celle-ci
- Liez vers des sites et sources externes plutôt que de citer ou de réécrire une documentation existante
- Assurez-vous que les sites vers lesquels vous liez sont de haute qualité
- Si le lien permet de télécharger un fichier, mentionnez-le explicitement — indiquez également le type de fichier téléchargé et une estimation approximative de sa taille
Code dans la documentation
- Utilisez des blocs de code avec une coloration syntaxique spécifique au langage lorsque possible pour les grands exemples de code
- Si ce n’est pas déjà évident, introduisez un exemple de code par une phrase d’introduction qui lance l’exemple qui suit — en cas de doute, privilégiez l’explication
- Les exemples de code doivent suivre les meilleures pratiques d’écriture de code pour le langage de programmation concerné
- Utilisez du code en ligne pour exprimer des attributs de code de base ou lorsqu’un bloc de code complet n’est pas nécessaire, tels que :
- Noms et valeurs d’attributs
- Noms de classes
- Noms d’utilitaires en ligne de commande
- Types de données
- Noms de variables d’environnement
- Noms de fichiers, extensions de fichiers et chemins
- Dossiers et répertoires
- Verbes HTTP, codes de statut et valeurs de type de contenu
- Noms et valeurs de paramètres de requête
- Saisie de texte
- Lorsque vous utilisez un marqueur de position dans des exemples de code, des commandes ou d’autres textes, incluez une explication de ce que représente le marqueur de position
- Écrivez une explication la première fois que vous utilisez le marqueur de position ; s’il y a plusieurs marqueurs de position ou étapes après la première utilisation de ce marqueur, vous pouvez réexpliquer le marqueur
- Fournissez un moyen simple pour les utilisateurs ou les développeurs de copier et d’exécuter le code.
- Montrez la sortie attendue, soit dans une section séparée après l’exemple de code, soit en utilisant des commentaires de code dans l’exemple de code
- Écrivez du code sécurisé — ne codez jamais en dur les mots de passe, les clés API ou les informations sensibles dans le code
Procédures et guides étape par étape
- Formatez les procédures de manière cohérente afin que les lecteurs puissent les trouver facilement en parcourant le texte
- Utilisez une entrée numérotée séparée pour chaque étape
- Incluez les actions qui finalisent une étape, telles que les boutons OK ou Appliquer
- Si l’instruction apparaît dans la même interface utilisateur où l’action se produit, il n’est généralement pas nécessaire de fournir des détails d’emplacement
- Si vous devez vous assurer que le lecteur commence au bon endroit, fournissez une brève phrase au début de l’étape
Accessibilité et inclusivité
- Utilisez des captures d’écran, des diagrammes ou des vidéos lorsqu’ils ajoutent de la valeur, en particulier pour expliquer des étapes complexes ou montrer des parties d’une interface
- Les images doivent être utilisées pour étayer les informations textuelles, pas pour les remplacer
- Utilisez toujours des attributs
altpour les images - Fournissez toujours des légendes ou des transcriptions pour les vidéos
- N’utilisez des GIF que si vous pouvez totalement expliquer le contenu dans le texte
- Choisissez des images simples et recadrez les détails superflus
- Utilisez un langage simple et évitez les figures de style ou les idiomes qui pourraient ne pas être universellement compris
- Considérez que votre document sera utilisé sur une multitude d’appareils
- Utilisez un langage neutre en matière de genre. N’utilisez pas il, lui, son, elle, sa, ou siens/siennes lors de la référence aux personnes — pour contourner les pronoms, vous pouvez :
- Réécrire en utilisant la deuxième personne (vous)
- Réécrire la phrase pour avoir un nom pluriel et un pronom pluriel
- Utiliser les mots personne ou individu
- Utiliser les articles le, un, ou une au lieu d’un pronom
- Utiliser un pronom pluriel tel que ils, leur ou eux, même s’il fait référence à un seul individu
- Lorsque vous écrivez à propos d’une personne réelle, utilisez les pronoms que cette personne préfère
- Soyez inclusif en matière d’identité de genre, de race, de culture, de religion, de capacité, d’âge, d’orientation sexuelle et de classe socio-économique — incluez une grande variété de professions, de cultures, de contextes éducatifs, de lieux et de contextes économiques dans les exemples
- Évitez les contenus politisés — dans les cas où un contenu politique doit être inclus, restez neutre
- Ne faites aucune généralisation sur les personnes, les pays et les cultures, même positives ou neutres
- N’écrivez pas de contenu préjudiciable et discriminatoire contre des communautés, en particulier les minorités
- Évitez les termes qualitatifs liés à des événements historiques
- Évitez d’utiliser des termes et des métaphores associés à la violence et aux actions militaires
.
). Bonne remarque sur l’incohérence cependant. Je ne suis pas sûr de celui que nous choisirons, mais nous nous assurerons certainement d’en choisir un et de nous y tenir. 