En tant que personne contribuant à la base de connaissances, vous utilisez des mots pour aider un demi-milliard de personnes. C’est une tâche considérable. Les utilisateurs et utilisatrices consultent la base de connaissances depuis le monde entier et s’attendent à des solutions faciles, mais nous voulons aussi les enchanter par notre ton. Comment faire ? Voici quelques éléments que nous avons trouvés lors de nos recherches.

Ton

Écrivez en gardant la marque à l’esprit. Mozilla, c’est le choix de l’utilisateur ou de l’utilisatrice. Nous croyons en la liberté et la flexibilité. Nous attachons de l’importance à la vie privée et à la sécurité. Nous sommes une organisation à but non lucratif animée par une communauté de bénévoles du monde entier qui partagent des valeurs communes.

Il n’est pas nécessaire de marteler cette histoire chaque fois que vous écrivez un article. C’est juste quelque chose à garder à l’esprit lorsque vous décrivez des fonctionnalités.

Style d’écriture

Écrivez pour un public général et non technique.

Nous voulons que nos articles soient utilisables par tout le monde, pas seulement par les utilisateurs et utilisatrices avancées. Cela signifie que nous écrivons pour un public général plutôt que pour un public très familier avec les techniques et la terminologie informatiques. Supposez que la personne pour qui vous écrivez ne sait pas comment modifier les préférences ou ajouter un bouton à la barre d’outils sans instructions pas à pas. Nous devons également supposer qu’elle n’a modifié aucun des paramètres par défaut de l’application ou du système d’exploitation.

Pour résumer, vous devriez suivre ces lignes directrices :

1. Soyez bref. Les gens viennent à la base de connaissances en cherchant des solutions rapides. Ils ne se soucient peut-être pas du fonctionnement interne de l’outil – ils veulent juste savoir ce qu’ils doivent faire pour le réparer. N’hésitez pas à supprimer des mots. Voyez tout ce que vous pouvez exprimer avec moins de mots. C’est comme de la poésie !
2. Soyez clair. Évitez le jargon. Soyez précis. Utilisez dans le titre et dans l’article des mots que la personne qui lit utiliserait. Si votre neveu de 13 ans ne le comprend pas, écrivez-le pour qu’il le comprenne. Consultez la section suivante pour un guide plus complet.
3. Soyez amical, amusant et empathique (en bref : soyez humain). D’accord, les utilisateurs et utilisatrices ne s’attendent pas à s’amuser en consultant l’assistance. C’est ce qui rend cela puissant. Égayez la journée de la personne qui vous lit avec un peu d’humour. Mais veillez à ne pas sacrifier la clarté en utilisant des métaphores ou des expressions amusantes. Si vous ne savez pas comment trouver cet équilibre, écrivez simplement des instructions directes et utilisez ce ton dans l’introduction ou la conclusion.
4. Racontez une histoire. Ayez un début, un milieu et une fin. Mais n’écrivez pas un roman (voir la ligne directrice n° 1).
   • Début : cela donne au lecteur ou à la lectrice un peu de contexte. De quoi parle cet article et pourquoi devrais-je m’y intéresser ? Soyez bref.
   • Milieu : les instructions vont ici. Cela devrait répondre à « Comment puis-je faire cela ? »
   • Fin : y a-t-il des étapes suivantes à l’article ou à la fonctionnalité ? Dites à la personne qui lit où elle doit aller ensuite si elle veut en savoir plus.

Lisez la section suivante pour des lignes directrices plus complètes.

Style d’écriture (exhaustif)

• Style d’écriture conversationnel – Utilisez un style informel et actif semblable à la manière dont vous parleriez en personne à quelqu’un.
• Humour et émotion – L’utilisation de l’humour est une bonne chose, mais il est parfois difficile, voire impossible, de le localiser. Les émotions comme la surprise et « Je ne savais pas ça/Eurêka ! » pourraient être plus faciles à inclure.
• Multiples styles d’apprentissage – Comme à l’école, les gens apprennent différemment. Ainsi, tout le monde tire profit de voir le même contenu exprimé de multiples façons.
• Répétition – Quand vous expliquez quelque chose de différentes manières avec différents médias, vous êtes évidemment en train de le répéter, ce qui est un autre bon moyen d’aider les gens à se souvenir de ce qui est important.
• Images et vidéo – Utiliser des images et des vidéos avec du texte est non seulement ce qui se rapproche le plus d’une aide en personne, mais c’est aussi un moyen facile d’inclure plusieurs styles d’apprentissage et la répétition. Trop d’images, cependant, peuvent rendre la localisation d’un article plus difficile, alors essayez de n’ajouter des images que lorsque c’est utile pour une étape ou un concept. Par exemple, pour une étape qui consiste à cliquer sur un bouton, vous pourriez dire « Cliquez sur OK » au lieu d’ajouter une capture d’écran de la boîte de dialogue de ce bouton.
• Activités – Particulièrement dans un tutoriel, il est bon de donner aux gens quelque chose d’utile à accomplir. C’est une chose de lire des instructions et de comprendre le processus, mais il est souvent utile de rappeler aux gens d’essayer les choses et de leur en donner les moyens.

Types d’articles

L’utilisation de types de contenu cohérents pour nos articles de la base de connaissances présente de nombreux avantages, notamment une navigation plus facile et une clarté et une organisation améliorées, en plus de nous aider à créer du contenu plus efficacement. Nous sommes en train de passer à une catégorisation des articles externes de la base de connaissances en quatre types, chacun ayant un objectif spécifique :

• À propos : ces articles répondent aux questions « Qu’est-ce que… », en fournissant des informations essentielles pour aider les lecteurs et lectrices à comprendre un sujet.
• Tutoriel : ces articles se concentrent sur les réponses aux questions « Comment… ? », en guidant les lecteurs et lectrices à travers les étapes nécessaires pour atteindre un objectif ou une procédure spécifique.
• Dépannage : ces articles aident les utilisateurs et utilisatrices à identifier, diagnostiquer et résoudre les problèmes courants qu’ils peuvent rencontrer avec un produit, un service ou une fonctionnalité en répondant aux questions « Comment… ? » liées à la résolution de problèmes.
• FAQ : ces articles contiennent des réponses concises aux questions fréquemment posées sur un seul sujet, qui peuvent ne pas trouver leur place dans d’autres articles individuels de la base de connaissances, fournissant une référence rapide pour les demandes courantes.

Commencer par un titre efficace et descriptif

Un titre bien conçu est plus qu’une simple étiquette ; c’est le premier point de contact d’un utilisateur ou d’une utilisatrice avec votre article de la base de connaissances. Un bon titre doit non seulement attirer l’attention de la personne qui lit, mais aussi servir d’aperçu concis et informatif du contenu de l’article. Lors de la création de titres pour SUMO, tenez compte des points suivants :

• Clarté et description : correspondez à ce dont parle l’article et à ce que la personne recherche. Soyez concis, mais centré sur l’utilisateur ou l’utilisatrice.
• Inclusion de mots-clés : incorporez des mots-clés pertinents pour améliorer la visibilité dans les moteurs de recherche et aider les gens à trouver votre article.
• Concision : gardez des titres brefs tout en fournissant des informations adéquates. Les titres plus courts sont often plus conviviaux. Essayez de garder des titres d’environ 60 caractères
• Orienté vers l’action : utilisez des verbes d’action le cas échéant pour indiquer ce que les utilisateurs et utilisatrices peuvent faire pour résoudre un problème ou atteindre un objectif. Évitez d’utiliser des gérondifs (mots se terminant par « ing » en anglais) dans les titres pour vous assurer qu’ils restent orientés vers l’action. Évitez d’utiliser des titres contenant « Comment… »

Rédiger une bonne introduction

Avec le titre et la table des matières, l’introduction est ce qui aidera l’utilisateur ou l’utilisatrice à déterminer s’il ou si elle est au bon endroit.

• Pour un article de type « À propos » : fournissez un aperçu textuel ou une définition du concept et concentrez-vous sur la raison pour laquelle la personne qui lit devrait s’y intéresser.
• Pour un article de type « Tutoriel » : fournissez un aperçu textuel ou une définition de la tâche et concentrez-vous sur l’importance ou les avantages de la tâche.
• Pour un article de type « Dépannage » : décrivez le problème spécifique ou les symptômes que les utilisateurs et utilisatrices peuvent rencontrer. Rédigez dans un langage clair et concis, en évitant le jargon technique autant que possible.

Gardez à l’esprit qu’une bonne introduction peut généralement servir de bon résumé de recherche. Souvent, vous pouvez simplement la copier dans le champ « Résumé pour les résultats de recherche » et c’est tout.

Organiser l’article efficacement

L’idée générale ici est d’essayer de construire des compétences de la plus simple à la plus complexe tout en essayant de garder les informations nécessaires à la plupart des gens en haut. Donc une solution simple et courante viendrait généralement avant une solution complexe ou un cas limite.

Rendre les instructions pas à pas faciles à suivre

La chose principale à garder à l’esprit lors de la rédaction d’instructions pas à pas est de veiller à inclure toutes les actions nécessaires pour accomplir la tâche. Si, par exemple, vous devez cliquer sur OK après avoir sélectionné une préférence pour passer à l’étape suivante, veillez à inclure le clic sur « OK » dans cette étape. Quelques points supplémentaires à prendre en compte :

• Il y a toujours plusieurs façons d’arriver à un résultat. Nous devrions toujours choisir la façon la plus conviviale en utilisant l'interface utilisateur graphique et les menus lorsque c’est possible.
• Utilisez des phrases complètes pour décrire comment accéder à l’interface utilisateur.
• Incluez les résultats attendus lorsque vous donnez des instructions (par exemple, Cliquez sur « OK » et la fenêtre se fermera.).

Lisibilité

Le texte doit être lisible. Pour ce faire, vous devez :

• Diviser un article en petits blocs logiques/sémantiques avec des sous-titres.
• Utiliser des listes numérotées ou à puces.
• Rédiger des phrases courtes ou relativement courtes.
• Éviter d’écrire de longs paragraphes.

Il n’y a pas de limite à la quantité de texte. Plus il y a de matière, mieux c’est ; cependant, vous ne devez pas l’étoffer artificially. Fournissez uniquement des informations utiles, précieuses et nécessaires.

Comment créer des liens vers la documentation externe de logiciels tiers

Lors de la création ou de la mise à jour d’articles qui impliquent des actions dans des logiciels tiers, tels que des systèmes d’exploitation ou des applications externes, il est crucial de fournir aux utilisateurs et utilisatrices des informations précises et fiables. Cependant, l’inclusion d’étapes directes pour ces logiciels dans nos articles peut présenter des défis :

• Informations rapidement obsolètes : les mises à jour de logiciels tiers peuvent rendre nos instructions obsolètes, ce qui peut dérouter ou induire en erreur nos utilisateurs et utilisatrices.
• Gourmand en ressources : le suivi et la mise à jour continus des étapes pour plusieurs plateformes externes nécessiteraient des efforts et des ressources considérables, ce qui n’est peut-être pas réalisable.

Bonnes pratiques

Pour garantir que nos utilisateurs et utilisatrices reçoivent les informations les plus fiables et les plus à jour sans surcharger nos ressources, suivez ces bonnes pratiques :

• Lien vers les ressources officielles : chaque fois que les instructions impliquent un logiciel tiers, trouvez la documentation officielle ou les articles d’aide fournis par le fabricant du logiciel. Créez un lien vers ces ressources au lieu d’écrire les étapes directement dans nos articles.
• Fournir un contexte : expliquez brièvement pourquoi vous dirigez la personne vers une page externe (par exemple : « Pour les étapes les plus récentes et les plus précises pour ajuster les paramètres de votre système, veuillez vous référer à la page d’assistance officielle de [nom du logiciel] »).
• Vérifier les liens périodiquement : bien que nous visions à réduire la maintenance des instructions de tiers, il est toujours important de vérifier périodiquement que les liens externes sont toujours valides. Si vous remarquez qu’un lien est devenu obsolète ou brisé, recherchez un lien mis à jour vers la documentation officielle et soumettez une révision.
• Avis de non-responsabilité sur le contenu externe Lorsque vous dirigez des personnes vers un lien externe, indiquez clairement qu’elles quitteront SUMO et que nous ne sommes pas responsables du contenu des sites externes. Un simple avertissement ou une note peut suffire (par exemple « Suivre ce lien vous redirigera vers un site web externe qui n’est pas exploité par Mozilla. »).

Exemple

Imaginez que vous rédigez un article sur la configuration d’une fonctionnalité de Firefox qui repose sur la modification des paramètres au niveau du système sur un Mac. Au lieu de décrire les étapes directement dans l’article, vous pourriez écrire :

« Pour connaître les dernières étapes de réglage des préférences de votre système sous macOS, veuillez consulter la documentation d’assistance officielle d’Apple en visitant ce guide. Veuillez noter que suivre ce lien vous dirigera vers un site web externe qui n’est pas exploité par Mozilla. »

Cela garantit que vous suivez les instructions les plus récentes directement depuis la source.

Lignes directrices techniques

• Pour apprendre à créer un nouvel article, consultez Create a new Knowledge Base article.
• Pour apprendre à modifier un article existant, consultez Modifier un article de la base de connaissances.
• Consultez Comment la base de connaissances fonctionne pour un aperçu du fonctionnement de la base de connaissances.
• Consultez Améliorer la base de connaissances en anglais pour une liste complète de la documentation sur les articles.

Titre

• Longueur du titre : la page de résultats de recherche de Google affiche jusqu’à 60 caractères. Votre titre peut être plus long si nécessaire, mais assurez-vous que vos mots-clés importants sont inclus dans les 60 premiers caractères.
• Casse : utilisez la casse de phrase. Le premier mot du titre doit être en majuscule, ainsi que les noms propres et les noms, et non chaque mot principal. Utilisez le style « phrase », pas le style « titre » (il en va de même pour les titres de section). Consultez la section Guide de style et règles de rédaction ci-dessous pour d’autres règles sur la capitalisation.
• N’utilisez pas le signe deux-points dans le titre de l’article, car cela empêche la création d’un lien wiki vers cet article (bogue 749835). Assurez-vous également de ne pas avoir d’espaces supplémentaires dans le titre de l’article, ce qui empêchera également les liens wiki de fonctionner.
• Essayez de varier la façon dont vous nommez les articles. N’utilisez pas les mêmes mots ou phrases dans chaque titre. Par exemple, ne commencez pas toujours les articles par « Comment » et évitez d’utiliser des noms de tâches en « ing » comme « Setting the home page ».
• N’oubliez pas que toute l’explication ne doit pas figurer dans le titre. Vous pouvez utiliser le résumé pour donner à la personne qui lit des informations supplémentaires sur le contenu de l’article.

Slug

Lorsque vous créez un nouvel article et saisissez un titre, SUMO crée automatically un slug (la partie après kb/ à la fin de l'URL de l’article). Une personne chargée de la relecture peut modifier le titre d’un article existant, mais le slug reste le même, sauf s’il est modifié manuellement (c’est voulu). Le slug est limité à 50 caractères. Les espaces sont remplacés par des tirets. Le slug doit être cohérent avec le titre, mais compte tenu de la contrainte d’espace plus stricte, il n’a pas besoin d’être le même.

Corriger le slug

Veillez à vérifier la fin du slug généré automatiquement. Parfois, un mot est coupé ou il se termine par un tiret. Veuillez corriger ce genre de choses.

Mettre à jour le slug d’un article existant

Lorsque vous mettez à jour le titre d’un article existant, ne modifiez pas le slug actuel, sauf si le nouveau titre représente un changement important qui ne correspond plus au slug existant. Garder le slug cohérent permet d’éviter les liens brisés et de préserver la valeur SEO.

Catégories, produits et sujets

Pour la plupart, un article appartient soit à la catégorie Tutoriel, soit à la catégorie Dépannage. Occasionnellement, nous écrivons des articles dans l’une des autres catégories, comme les articles « Comment contribuir » (comme celui-ci). La page d’historique de l’article indique la catégorie.

Les articles sont également « pertinents pour » au moins un produit. Ils appartiennent également à un « sujet » principal et, éventuellement, à un « sous-sujet ».

Mots-clés

Le champ des mots-clés dans un article peut être utilisé pour améliorer les résultats de recherche sur SUMO. Il ne devrait néanmoins être utilisé que sous certaines conditions bien particulières, sa mauvaise utilisation pouvant biaiser la recherche. Nous avons rarement besoin d’utiliser les mots-clés. Pour en savoir plus, consultez l’article Quand et comment utiliser les mots-clés pour améliorer le classement de recherche d’un article.

Rédiger un bon résumé de recherche

Le résumé de l’article, ainsi que le titre, aide les utilisateurs et utilisatrices à juger si un article répondra à leur question. Nous appelons cela la « confiance de l’utilisateur » et cela a un impact direct sur les taux de clics. Même si nous proposons le bon article en haut de la liste des résultats de recherche, la personne doit faire le lien mental entre la requête de recherche et les résultats que nous affichons pour qu’elle clique sur l’article.

Un résumé pour un article de tutoriel doit inclure les sujets traités dans l’article. Un article de dépannage doit essayer d’inclure les symptômes. De plus, un résumé doit suivre ces lignes directrices :

• Court et direct. Vous vous souvenez des petites annonces ? Rédigez-le comme ça. Les moteurs de recherche peuvent couper tout ce qui dépasse 140 caractères. Si vous utilisez un résumé plus long, gardez les informations importantes au début. Note : le logiciel de la base de connaissances affichera 20 caractères restants lorsque le résumé atteindra 140 caractères, car la limite de recherche interne est de 160.
• N’utilisez pas de balisage wiki.
• N’utilisez pas « Cet article explique » dans chaque résumé. Variez lorsque c’est possible. Voici d’autres phrases à envisager :
  • Nous vous montrerons
  • Nous vous expliquerons
  • Cette page explique
  • Cet article décrit
  • Apprenez comment

Nombre d’étapes

Lorsque vous guidez les utilisateurs et utilisatrices à travers un processus, envisagez d’utiliser des listes ordonnées (listes numérotées). C’est généralement une bonne pratique d’essayer de garder le nombre total d’étapes entre six et sept.

Structure parallèle

Utilisez la même formulation ou le même modèle de mots pour chaque étape que vous écrivez. La structure parallèle est importante dans les articles de la base de connaissances, car elle rend les choses claires et faciles à suivre. Lorsque des éléments similaires ont un format cohérent, les utilisateurs et utilisatrices peuvent comprendre et accomplir les tâches plus facilement. Cette structure simplifie les instructions, réduit les erreurs et garantit que les informations sont transmises efficacement.

Par exemple :

1. Trouvez Vider l’historique lors de la fermeture de Firefox. Si cette case est cochée :
   1. Cliquez sur le bouton Settings….
   2. Assurez-vous que Historique des formulaires et de la recherche n’est pas coché.
   3. Cliquez sur OK.

Repères directionnels

Les repères directionnels sont des références ou des indicateurs qui guident les utilisateurs et utilisatrices vers l’emplacement ou la position spécifique dans une interface utilisateur où ils doivent effectuer une action particulière. Ces repères aident les gens à naviguer et à interagir plus efficacement avec les logiciels, les applications ou les sites web. Ils comprennent généralement des phrases comme « Dans le coin supérieur droit », « Dans le menu de gauche » ou « Sous la barre de recherche », qui donnent aux utilisateurs et utilisatrices une idée claire de l’endroit où trouver et effectuer des actions.

Dans les instructions de vos articles de la base de connaissances, veillez à fournir des repères directionnels avant l’action. Par exemple, au lieu de dire Cliquez sur le bouton, utilisez Dans le coin supérieur droit, cliquez sur le bouton. Ce format aide les utilisateurs et utilisatrices à localiser et à effectuer facilement des actions dans l’interface.

Guide de style et règles de rédaction

Comme nous l’avons dit précédemment, vous devez utiliser un style actif et conversationnel lorsque vous écrivez. Évitez de dire des choses comme « Si les marque-pages d’un utilisateur ont été perdus » et dites plutôt « Si vous avez perdu vos marque-pages ». Voici d’autres problèmes courants de style et de rédaction que vous pouvez rencontrer lors de la rédaction d’articles d’assistance : Utilisez toujours les termes tels qu’ils apparaissent dans l’interface de Mozilla. Par exemple :

• Plugins n’a pas de trait d’union.
• Add-ons a un trait d’union.
• Home page est en deux mots.

Termes informatiques généraux :

• Website (site web) est en un seul mot. Web page (page web) est en deux mots.
• Log in et log out sont des verbes. Exemple : « Log in to the website. » Il en va de même pour sign in et sign out. N’utilisez pas « log into » ou « sign into ».
• Login et logout sont des noms (généralement utilisés comme adjectifs). Exemple : « Click the login button. »
• Utilisez email au lieu d’e-mail.
• Le pluriel de CD-ROM est CD-ROMs.

Les liens vers mozilla.org ne doivent pas contenir la locale :

• Utilisez https://www.mozilla.org/ au lieu de https://www.mozilla.org/en-US/

Lorsque vous incorporez des liens dans des phrases :

• Évitez d’utiliser « cliquez ici » ou « ici » comme texte de lien.
  • À faire : allez dans les paramètres de votre compte pour annuler votre abonnement.
  • À ne pas faire : cliquez ici pour annuler votre abonnement.

Mettez en majuscule les éléments suivants :

• Les noms propres et les noms, y compris les noms de marque, de produit et de fonctionnalité
• Le premier mot d’une phrase complète
• Les lettres des abréviations et des acronymes, sauf s’ils sont normalement en minuscules
• Le premier mot des listes numérotées ou à puces
• Le nom d’une touche du clavier
• Le premier mot d’une phrase complète suivant un deux-points
• Le premier mot d’un titre de section ou d’article

Mozilla accounts:

• Le « a » de Mozilla accounts est toujours en minuscule, sauf dans les éléments de navigation où il est inclus avec d’autres éléments de navigation qui utilisent la casse de titre.
• Utilisez toujours « sign in » et « sign out ».
• Sous forme de verbe, utilisez « sign in to your account » (et non « sign into ») pour être grammaticalement correct.
• Vous pouvez également utiliser « Sign in with Mozilla ».
• « Sign » doit toujours être utilisé comme un verbe. Si vous l’utilisez comme un nom, utilisez « login ».
• Utilisez « sign up » comme appel à l’action pour créer un nouveau compte.

Pour plus de détails sur la façon de faire référence aux comptes Mozilla dans les articles de la base de connaissances, consultez Editorial guidelines for Mozilla accounts.

N’utilisez pas « i.e. » et « e.g. ». Ces abréviations latines peuvent dérouter les gens. Par souci de clarté, utilisez « c’est-à-dire » ou « autrement dit » au lieu de i.e. lorsque vous voulez expliquer quelque chose d’une manière différente. Utilisez « par exemple » ou « comme » au lieu de e.g. lorsque vous voulez donner des exemples.

N’utilisez pas de virgules de série dans une liste d’éléments. Par exemple, utilisez « Extensions, thèmes et plugins » (sans la virgule de série), et non « Extensions, thèmes, et plugins ».

Utilisez des sigles qui sont considérés comme étant généralement compris. Par exemple :

• HTTP
• USB
• URL

Les nombres apparaissant dans la version d’un produit, les codes d’erreur, les touches et les boutons ne seront pas écrits en toutes lettres.

Rédigez les instructions à la voix active. La voix active et le temps présent simplifient les instructions, les rendant plus faciles à suivre et encourageant une action rapide. Exemple :

« Redémarrez Firefox pour mettre à jour » et non « Firefox doit être redémarré ».

Épelez les barres obliques inverses (\\) et les barres obliques (/) pour les chemins et les recherches afin d’éviter toute confusion.

Exemple : « Certains chemins d’accès aux images contiennent des barres obliques inverses (\\\\) ».

Raccourcis clavier Mettez en majuscule la première lettre d’un raccourci clavier ou d’une combinaison de raccourcis : Ctrl + Shift + C ou Command + Shift + C.

N’utilisez pas d'argot et d’expressions idiomatiques. Tous nos articles sont traduits dans de nombreuses langues différentes, ils sont donc lus et traduits par des personnes dont l’anglais n’est pas la langue maternelle. L’argot et les expressions idiomatiques peuvent être ambigus, ce qui peut dérouter les lecteurs et lectrices et rendre la traduction plus difficile.

Nous avons des styles visuels spéciaux pour un certain nombre d’éléments qui peuvent être obtenus en ajoutant le balisage wiki approprié autour de l’élément. Consultez Mémo pour la syntaxe wiki de SUMO pour les styles les plus courants.

Nous avons un balisage wiki spécial – {for} – qui vous permet de cibler des informations pour des versions spécifiques de Firefox ou des systèmes d’exploitation spécifiques. Par exemple, vous affichez un ensemble d’instructions pour les personnes exécutant Windows et un autre pour les personnes utilisant macOS X (voir Comment utiliser les balises « for » pour plus de détails).