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 qu'Unraid OS s'adresse à un public mondial, nous évitons le jargon, l'argot ou les expressions idiomatiques. Ceux-ci peuvent confondre les locuteurs non natifs en anglais 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 | Italiques | *texte* | Entrez une valeur de 50gb |
| 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 Cases à Cocher | Gras | étiquette_case | Étiquette d'une option de case à cocher |
| Option de menu déroulant | Italiques | option_déroulante | Option sélectionnable dans un menu déroulant |
| Titre de la Boîte de Dialogue | Titre de Niveau 3 | ### Titre de la Boîte de Dialogue | Titre pour les dialogues pop-up ou les fenêtres modales |
| Texte de l'Infobulle | Italiques en Ligne | texte d'infobulle | Courte explication affichée au survol |
| Élément de Menu | Gras + italiques | 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 ou journaux d'erreur exacts |
| Titre du Document | Titre de Niveau 1 | # Titre | (rend comme) <h1>Titre</h1> |
| Section du document | Titre de Niveau 2 | ## Titre | (rend comme) <h2>Titre</h2> |
| Sous-section du document | Titre de Niveau 3 | ### Titre | (rend comme) <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 à assimiler, à se souvenir et à suivre les points ou les étapes clés. Il existe deux principaux types, chacun avec des cas d'utilisation clairs :
-
Listes non ordonnées (puces) : Utiliser pour regrouper des éléments connexes sans impliquer d'ordre. Exemple : "Liste des outils courants d'Unraid OS."
-
Listes ordonnées (numérotées) : Utiliser pour montrer une séquence ou une 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.
- Épelez toujours les acronymes ou les sigles peu communs la première fois qu'ils sont utilisés, suivis de l'abréviation entre parenthèses. Exemple : Virtual Machine Disk (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 lignes directrices 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 :
Vous pouvez également consulter notre [guide de démarrage rapide](../unraid-os/getting-started/quick-start-guide.mdx).
- Lien toujours vers la ressource la plus pertinente et autoritaire disponible.
Ajouter des termes de glossaire
Les documents Unraid utilisent un système centralisé de glossaire pour garantir la cohérence et l'accessibilité des termes techniques. Les entrées du glossaire sont conservées 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: Nom à afficher
def: Texte complet de la définition.
link: <a href="https://example.com">Lien détaillé facultatif</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.