Guide de style des documents Unraid
Unraid OS est façonné par l'équipe LimeTech et la communauté Unraid. Notre documentation vise à être exhaustive, précise et à jour. Étant donné que nos utilisateurs proviennent de divers horizons dans le monde entier, ce guide établit les bases d'une rédaction cohérente et claire dans l'ensemble des documents Unraid.
Conventions d'écriture
Style et ton
Notre ton trouve un équilibre entre amical et formel, visant un contenu détaillé et précis auquel les utilisateurs peuvent s'identifier.
- Utilisez des instructions formelles et directes lorsque l'action est fixe et ne laisse aucune place à la déviation.
- Utilisez un ton conversationnel et explicatif lorsque vous fournissez un contexte ou des scénarios pour rendre le contenu plus accessible.
En tant que contributeur, tenez compte du contexte et du public lors du choix de votre ton.
Parce que Unraid OS a un public mondial, nous évitons le jargon, l'argot ou les idiomes. Ceux-ci peuvent perturber les locuteurs non natifs et compliquer le processus de traduction.
Public : Écrire pour tous les niveaux
Nos lecteurs vont des experts Linux qui comprennent les entrailles du système aux débutants explorant Unraid pour la première fois.
Écrivez clairement et de manière inclusive afin que les experts comme les néophytes puissent suivre aisément.
La méthode ABC : précision, brièveté, clarté
Nous priorisons :
- Précision : Assurez-vous que le contenu est correct et rigoureusement testé.
- Brièveté : Soyez concis sans sacrifier les détails nécessaires.
- Clarté : Utilisez un langage simple et structurez le contenu pour une compréhension facile.
Syntaxe
Les documents Unraid utilisent le formatage Markdown combiné à des styles de texte spécifiques pour aider les utilisateurs à identifier rapidement les éléments de l'interface et à naviguer dans le WebGUI.
| Type d'élément | Convention de style | Syntaxe Markdown | Exemple / Description |
|---|---|---|---|
| Nom d'option ou de bouton | Gras | **texte** | Sélectionner Terminé |
| Valeur saisie par l'utilisateur | Italique | *texte* | Entrer une valeur de 50 Go |
| Chemin de navigation | Gras + italique; utiliser → | ***nav1 → nav2*** | Paramètres → Paramètres du disque |
| Étiquette d'onglet | Gras | nom_onglet | Nom d'un onglet à sélectionner |
| Étiquette de case à cocher | Gras | étiquette_case_à_cocher | Étiquette d'une option de case à cocher |
| Option de menu déroulant | Italique | option_déroulante | Option sélectionnable dans un menu déroulant |
| Titre de dialogue | Titre de niveau 3 | ### Titre de dialogue | Titre pour les dialogues pop-up ou les fenêtres modales |
| Texte de l'info-bulle | Italique en ligne | texte de l'info-bulle | Courte explication affichée au survol |
| Élément de menu | Gras + italique | Menu → Sous-menu → Élément | Navigation à travers les menus imbriqués |
| Sortie de la CLI et du système | Monospace (code en ligne) | `texte` | Naviguer vers http://tower.local |
| Message d'erreur | Monospace (code en ligne) | `Erreur : message` | Chaînes d'erreur ou journaux exacts |
| Titre du document | Titre de niveau 1 | # Titre | (affiché en tant que) <h1>Titre</h1> |
| Section du document | Titre de niveau 2 | ## Titre | (affiché en tant que) <h2>Titre</h2> |
| Sous-section du document | Titre de niveau 3 | ### Titre | (affiché en tant que) <h3>Titre</h3> |
Chaque niveau de titre 2 (##) ou inférieur apparaît dans la barre latérale du Table des Matières (TOC) pour une navigation facile.
Formatage des listes et tableaux
Utiliser des éléments structurés, tels que les listes et tableaux, améliore considérablement la clarté des informations, aide à la compréhension et favorise la consultation rapide.
Listes
Les listes aident les utilisateurs à absorber, se rappeler et suivre les points clés ou les étapes. Il existe deux types principaux, chacun avec des cas d'utilisation clairs :
-
Listes non ordonnées (à puce) : Utilisez-les pour regrouper des éléments connexes sans impliquer d'ordre. Exemple : "Liste des outils courants d'Unraid OS."
-
Listes ordonnées (numérotées) : Utilisez-les pour montrer une séquence ou procédure requise. Exemple : "Pour démarrer le array..."
- Essayez d'introduire la liste avec une phrase tige claire se terminant par un deux-points.
- Utilisez 4 à 6 éléments maximum dans une liste non ordonnée pour faciliter le balayage et la mémorisation. Les listes plus longues peuvent être mieux présentées sous forme de tableau.
Tableaux
Les tableaux sont un excellent moyen d'organiser des données connexes en regroupant les informations en lignes et colonnes, ce qui facilite les comparaisons rapides et précises.
- Utilisez des tableaux pour plusieurs points de données liés qui bénéficient d'une comparaison côte à côte.
- Évitez les tableaux avec seulement 1 ou 2 cellules; utilisez plutôt des listes à puces ou des phrases.
- Introduisez le tableau par une phrase expliquant son but et son contenu.
Abréviations, acronymes et sigles
Pour réduire la confusion des lecteurs, suivez ces principes concernant les abréviations :
- Abréviations : Ce sont des formes raccourcies de mots généralement inutiles dans les documents Unraid, sauf si elles sont universellement reconnues.
- Acronymes : Ils créent de nouveaux mots à partir des initiales d'autres mots (par exemple, RAID).
- Sigles : Utilisent des initiales prononcées individuellement (par exemple, OS, ZFS).
Recommandations :
- Préférez les acronymes ou sigles existants bien connus qui sont familiers à votre public.
- Évitez de créer de nouvelles abréviations juste pour être bref.
- Épélez toujours les acronymes ou sigles non courants la première fois qu'ils sont utilisés, suivis de l'abréviation entre parenthèses. Exemple : Disque de Machine Virtuelle (VMDK)
Créer des liens vers d'autres documents ou sites
Les liens stratégiques permettent aux lecteurs d'explorer des sujets connexes et améliorent leur compréhension. Utilisez ces directives pour un hyperlien pratique et accessible.
Directives pour le texte de lien
- Le texte de lien doit clairement décrire la destination, permettant à tous les lecteurs de comprendre le but du lien.
- Évitez les textes de lien vagues comme « Cliquez ici » ou « En savoir plus », car ils manquent de contexte.
- Évitez d'utiliser des URL brutes comme texte de lien en ligne.
Formatage des liens
- Utilisez des liens Markdown en ligne :
You can also check our [getting started guide](../unraid-os/getting-started/quick-start-guide.mdx).
- Lien toujours vers la ressource la plus pertinente et autoritaire disponible.
Ajouter des termes de glossaire
Unraid Docs utilise un système de glossaire centralisé pour garantir la cohérence et l'accessibilité des termes techniques. Les entrées de glossaire sont maintenues dans le fichier glossary.yaml situé dans le répertoire racine.
Pour ajouter ou mettre à jour un terme :
- Modifiez
glossaire.yamlen utilisant le modèle suivant :
GlossaryTerm:
term: Display Name
def: Full definition text.
link: <a href="https://example.com">Optional detailed link</a>
-
Pour ajouter une fonctionnalité d'info-bulle, référez-vous au terme dans la documentation en utilisant la syntaxe :
%%Term|GlossaryTerm%%...où la partie gauche de la barre verticale est le texte que vous souhaitez afficher, tandis que la partie droite est l'entrée correspondante du fichier YAML.
-
- La page du glossaire se mettra automatiquement à jour pour inclure de nouveaux termes.