Règles des listes dans la documentation technique

# Règles pour structurer les listes dans la documentation technique

Les listes offrent un bon équilibre entre la prose linéaire et les tableaux pour organiser l'information. Utilisez des listes numérotées pour les actions séquentielles où l'ordre importe : étapes d'installation, algorithmes. Utilisez des listes non ordonnées pour les collections d'éléments sans séquence stricte : paramètres, composants.

Gardez les listes à une longueur raisonnable. Des listes s'étendant sur des centaines de lignes sont difficiles à parcourir — divisez-les en sous-sections ou en tableaux.

Phrase d'introduction comme guide

Utilisez toujours une phrase introductive avant une liste pour définir son contenu. Elle fournit un contexte et relie les éléments entre eux.

Exemples de phrases d'introduction :

• Effectuez les actions suivantes pour initialiser :
• Paramètres de la fonction principale :
• Composants système requis :

Règles pour les former :

• Placez un terme unificateur (actions, paramètres, étapes) près de la fin.
• Évitez de spécifier le nombre d'éléments — cela peut devenir obsolète avec les changements.
• Si un terme spécifique ne convient pas, utilisez des génériques : élément, partie, étape.

Cela assure la cohérence et facilite la lecture.

Phrases nominales pour la cohérence

Formulez les éléments de liste comme des phrases nominales. Cela crée une structure uniforme et améliore la lisibilité. Exemple de transformation :

Incorrect : Le processus consiste en : ébavurage, préparation, expédition.

Correct : Le processus consiste en les étapes suivantes : ébavurage, préparation, expédition.

Toutes les lignes doivent être grammaticalement cohérentes, sans mélanger fragments de phrases et phrases complètes.

Éviter les répétitions dans les éléments

Les mots répétés au début des éléments de liste créent un effet de perroquet. Déplacez le mot commun dans la phrase d'introduction.

Exemple :

Incorrect :

• Bibliothèque A
• Bibliothèque B
• Bibliothèque C

Correct : Installez les bibliothèques suivantes :

• A
• B
• C

Cela raccourcit le texte et met l'accent sur les détails clés.

Listes à un seul élément

Les listes autonomes avec un seul élément perturbent l'uniformité et suggèrent des erreurs de formatage. Intégrez l'élément dans la phrase d'introduction.

Exemple : Au lieu d'une liste indiquant « Paramètre d'entrée : user_id », écrivez : « Le paramètre d'entrée user_id est l'identifiant de l'utilisateur ».

Ponctuation dans les listes

Maintenez la cohérence :

• Les lignes commençant par une majuscule se terminent par un point.
• Les lignes commençant en minuscules se terminent par un point-virgule.

Pour les éléments multiparagraphes, utilisez le premier style. Cela suit les normes de la documentation technique.

Règles pour les listes imbriquées

L'imbrication simplifie les structures hiérarchiques mais exige de la discipline.

Niveaux de numérotation :

• Niveau 1 : 1, 2, 3
• Niveau 2 : 1.1, 1.2
• Niveau 3 : 1.1.1, 1.1.2

Évitez les lettres et les chiffres romains — ils compliquent la navigation.

Limite d'imbrication : Pas plus de 5 niveaux. Si nécessaire, divisez en sous-sections. Quatre niveaux sont recommandés pour une lisibilité optimale.

Après les listes non ordonnées : Ne reprenez pas la numérotation. Cela évite l'ambiguïté.

Exemple d'une structure problématique :

• Niveau 1

1.1. Niveau 2

- Non ordonné

1.1.1? // Inclair

Points clés

• Utilisez des listes numérotées uniquement pour les séquences ; listes non ordonnées pour les ensembles.
• Phrase d'introduction avec un terme unificateur obligatoire — sans quantité spécifiée.
• Phrases nominales et absence de répétitions dans les éléments.
• Maximum 5 niveaux d'imbrication ; la numérotation ne se poursuit pas après les puces.
• Ponctuation : point pour les lignes en majuscule, point-virgule pour les minuscules.

Les listes améliorent la lisibilité dans les textes techniques comme la documentation, les guides et les articles. Suivre ces règles minimise la charge cognitive pour les développeurs intermédiaires et seniors ainsi que les spécialistes techniques.

— Editorial Team