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.

  • When describing a step, include a lead-in sentence to remind the reader what they will be doing when following the sub-steps.

  • Aim for no more than four sub-steps in any primary step.

  • If you are indenting sub-steps beyond one indent level, break out your steps into a new main step block.

  • Too many sub-steps could suggest that you need to break out some of these steps into a new step section.

  • Screenshots and images are recommended, particularly if you can include call outs to the specific parts of the screen you are referring to.

  • Identify steps that are optional by using typing Optional followed by a colon. For example,

    • Optional: Enter a description for your repository.

  • Use conditional clause if (condition) then (result) to identify steps that are applicable only if certain criteria apply. Always start the conditional steps with a condition so that users who do not meet the condition can skip the step. For example,

    • If you are a Windows user, then install the VM VirtualBox software on your machine.

For more information on writing procedures, see the Google developer documentation style guide.

Page structure

  • Create an outline of the headings you want to include in the document before you start writing.

    • Use the outline to gather your thoughts about the main topics you need to tell your readers.

    • It’s a lot easier to move things around with headings than to move blocks of content.

  • You may also find that you need to create two articles if the subject starts to branch.

  • Add any links you mention in the body of your content into the “See also” section. The inline links may get lost in long articles, and scanning for links adds to your audience’s cognitive load.

Titles and filenames

  • Make the title descriptive of the content contained within the article.

  • Make the title unique within your application space.

  • Make the title and filename the same: it makes it difficult to identify the file name when the title and filename differ.

  • Use unique words in titles so you can search and replace text later on without getting fuzzy matches.

Here are some title examples and their suggested file name structures:

  • Using a toaster

    • using-a-toaster.rst

  • Toast a slice of bread

    • toast-slice-of-bread.rst

Definitions

If you are repeatedly using terms throughout a large article, you can define them once and then use them repeatedly in the body of the article.

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