Directives générales de rédaction

Suivez ces conseils éditoriaux pour la rédaction de contenu en utilisant The Good Docs Project templates.

Langage et ton

  • Utilisez un vocabulaire, une orthographe et un ton cohérents dans l’ensemble de vos documents.

  • Décrivez les choses aussi clairement et précisément que possible.

  • Passez votre texte dans un vérificateur de grammaire afin d’en vérifier la lisibilité.

    • Des outils tels que Grammarly vous aident à identifier des problèmes de grammaire

    • Des outils tels que Vale vous aident à repérer des problèmes de style.

    • Cet article inclut une liste d’autres outils de vérification.)

  • Évitez les expressions familières et tout jargon qui rendraient difficile la compréhension de votre texte par une personne dont le français n’est pas la langue maternelle.

  • Évitez d’inclure dans votre documentation des acronymes sans les développer lors de leur première mention. Vous pouvez utiliser l’acronyme pour les mentions suivantes.

  • Évitez d’inclure vos propres opinions, ou les opinions d’autres personnes. Cela empêche le lecteur de tirer des conclusions à partir de la documentation.

Rédaction des étapes procédurales

Voici quelques recommandations que vous pouvez suivre lorsque vous créez des étapes procédurales :

  • Pour des procédures avec de nombreuses étapes, veillez à « segmenter » le contenu en sous-sections de 5-1 étapes. Cela rend l’information plus facile à lire et se souvenir, et donne au lecteur un sentiment d’achèvement après la réalisation de chaque segment. Segmenter est recommandé par de grandes sociétés, telles que Mircrosoft et son “Writing style guide”, ainsi que le`Research on chunking and usability <https://www.nngroup.com/articles/short-term-memory-and-web-usability/>` du Nielsen Norman Group __.

  • Chaque étape est rédigée en une seule phrase (vous devriez pouvoir la lire à haute voix et a du sens grammaticalement parlant).

  • Dans la description d’une étape, insérez une phrase d’introduction pour rappeler au lecteur ce qu’il est sensé faire en suivant les étapes intermédiaires.

  • Pas plus de quatre étapes intermédiaires pour chaque étape principale.

  • Si vous souhaitez insérer des étapes intermédiaires au-delà d’un premier niveau, déplacez ces étapes dans un nouveau bloc d’étapes principales.

  • Trop d’étapes intermédiaires pourraient vous inciter à en reclasser certaines en une nouvelle étape.

  • Les captures d’écran et les images sont conseillées, en particulier si vous pouvez inclure des explications sur les parties spécifiques de l’écran auquel vous vous référez.

  • Indiquez les étapes facultatives en tapant Facultatif suivi de deux points. Par exemple,

    • Facultatif : Saisissez une description de votre dépôt.

  • Utilisez les clauses conditionnelles si (condition) alors (résultat) pour marquer les étapes qui ne sont applicables que si certains critères sont remplis. Commencez toujours une étape conditionnelle par une condition pour que les utilisateurs qui ne remplissent pas cette condition puisse éviter l’étape. Par exemple,

    • Si vous êtes sous Windows, alors installez le logiciel VM VirtualBox sur votre ordinateur.

Pour plus d’informations sur la rédaction de procédures, consultez le Google developer documentation style guide.

Structure de la page

  • Faites un plan avec les titres que vous souhaitez inclure dans votre document avant d’en commencer la rédaction.

    • Utilisez le sommaire pour rassembler vos pensées sur les sujets principaux dont vous souhaitez faire part à vos lecteurs.

    • Il est plus facile de déplacer le contenu avec des titres plutôt que déplacer des blocs de contenu.

  • Vous pourriez aussi vous rendre compte que vous devez créer deux articles si le sujet commence à se ramifier.

  • Ajouter dans la section « Voir aussi » tout lien dont vous parlez dans le corps de votre procédure. Les liens intégrés pourraient se perdre dans de longs articles, et devoir les rechercher dans le texte ne ferait qu’augmenter la charge cognitive de votre public.

Titres et noms de fichiers

  • Rendez le titre descriptif du contenu de l’article.

  • Rendez le titre unique dans l’espace de votre application.

  • Titre et nom de fichier doivent être identiques : il est plus difficile d’identifier le nom du fichier quand le titre et le nom du fichier sont différents.

  • Évitez les répétitions dans vos titres afin de pouvoir rechercher et remplacer du texte plus tard sans obtenir des correspondances approximatives.

Voila quelques exemples de titres et des suggestions de structure pour leur nom de fichier :

  • Utiliser un grille-pain

    • utiliser-un-grille-pain.rst

  • Griller une tranche de pain

    • griller-une-tranche-de-pain.rst

Définitions

Si vous utilisez à de multiples reprises des mots compliqués tout au long d’un long article, vous pouvez en donner une définition une fois puis les réutiliser à nouveau dans le corps de l’article.

Consultez les autres guides et modèles du The Good Docs Project.