Comment écrire les articles de la base de connaissances en anglais

Il y a beaucoup de choses en concurrence à soupeser quand vous écrivez ou modifiez un article. Vous voulez être, tout à la fois, complet et concis, factuel et intéressant. Ce n’est certainement pas la chose la plus facile au monde à faire. Voici des directives pour aider à rendre ce jugement un peu plus facile. Comme c’est également un wiki, nous pouvons toujours réviser quelque chose si nous nous sommes trompés.

Écrire pour un public général et non technique

Nous voulons que l’aide de Firefox soit utilisable par tous les utilisateurs de Firefox. Cela signifie que nous écrivons pour un public général plutôt que pour un familier avec les techniques et la terminologie informatique. Supposez que la personne pour laquelle vous écrivez ne connaisse pas la manière de changer les préférences ou d’ajouter un bouton de barres d'outils sans des instructions pas-à-pas. Nous devrions également supposer qu’ils n’ont changé aucun des réglages par défaut de Firefox ou du système d’exploitation.

Choisir un bon titre

Le titre de l’article ainsi que son résumé sont les seules choses dont l'utilisateur dispose pour juger de sa pertinence au regard de sa question. Nous appelons cela la « confiance utilisateur ». Elle impacte directement le taux de clic. » Même si nous servons le bon article en haut de la liste des résultats de recherche, l’utilisateur a besoin de connecter mentalement la requête et les résultats que nous affichons afin qu’il clique sur l’article.

Un titre d’article devrait essayer de décrire de quoi l'article traite. Il faut que les quelques premiers mots soient aussi compréhensibles que possible et comprennent les mots-clés importants. Cela permettra aux utilisateurs de savoir de quoi traite l’article et de cliquer dessus en toute confiance. De plus, un titre devrait suivre ces lignes directrices :

• Longueur du titre : La page des résultats de recherche de Google affiche jusqu’à 70 caractères. Votre titre peut être plus long que cela si nécessaire mais assurez-vous que les mots-clés importants sont dans les 70 premiers caractères.
• Essayez de varier la manière dont vous nommer les articles. N’utilisez pas les mêmes verbes ou phrases dans tous les titres.
• Essayez de ne pas utiliser le gérondif (mots se terminant par ing).
• N’utilisez pas de virgule dans le titre de l'article, car cela empêche la création d'un lien wiki vers cet article (bogue 749835).

Souvenez-vous que toute l’explication ne doit pas être dans le titre. Vous pouvez utiliser le résumé pour donner à l’utilisateur des informations supplémentaires sur ce qui est dans l’article.

Corriger l’identifiant

Quand vous créez un titre, SUMO crée également automatiquement un identifiant (la fin de l'URL de l'article). Il est limité à 50 caractères. Les espaces sont rendues par des tirets. L’identifiant devrait être cohérent avec le titre, mais, étant donné la contrainte de longueur limitée, n’a pas besoin d'être le même. Vérifiez bien la fin de l’identifiant autogénéré. Parfois, un mot est coupé ou l’identifiant se termine par un tiret. Veuillez corriger ce genre de choses.

Catégories, produits et sujets

Pour la majeure partie, un article appartient soit à la catégorie « Comment faire », soit à celle de « Résolution de problèmes ». De temps en temps, nous écrivons des articles « Comment contribuer » (comme celui-ci) ou quelque chose dans une des autres catégories.

Les articles concernent également au moins un produit. Ils appartiennent aussi à un « sujet » principal et, optionnellement, à 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.

Écrire un bon résumé de recherche

Le résumé de l’article ainsi que son titre sont les seules choses dont l’utilisateur dispose pour juger de sa pertinence au regard de sa question. Nous appelons cela la « confiance utilisateur ». Elle impacte directement le taux de clics. Même si nous servons le bon article en haut de la liste des résultats de recherche, l’utilisateur a besoin de connecter mentalement la requête et les résultats que nous affichons afin qu’il clique sur l'article.

Un résumé d’un article sur « Comment faire » devrait comprendre les sujets couverts dans l’article. Un article de résolution de problème devrait quant à lui inclure les symptômes. De plus, un résumé devrait suivre ces lignes directrices :

• Court et au fait. Souvenez-vous des petites annonces. Rédigez-le comme cela. La plupart des moteurs de recherche coupent tout ce qui dépasse 160 caractères.
• N’utilisez pas de balise wiki.
• N’utilisez pas « This article explains » dans tous les résumés. Variez autant que possible. Voici d'autres phrases à considérer :
  • We’ll show you
  • We’ll explain
  • This page explains
  • This article describes
  • We’ll spell out

Rendre votre écriture intéressante

L’aide de Firefox est un répertoire d’informations techniques sur l'utilisation du navigateur web Firefox. La documentation liste les fonctions des différentes fonctionnalités de Firefox, les procédures de diagnostic des problèmes et les instructions pour la résolution des problèmes courants. On peut accéder à la documentation en utilisant la fonction de recherche sur chaque page ou vous pouvez juste jeter votre ordinateur dans la pièce où des licornes utiliseront leurs pouvoirs arc-en-ciel pour devenir des bougies magiques qui, une fois consumées, vous feront devenir un ninja informaticien de niveau 70.

Vous êtes réveillé maintenant ? Bien.

Ce paragraphe semble un peu ennuyeux, au moins jusqu’à ce que les licornes apparaissent. L’utilisation de l’humour et des émotions (SURPRISE !) sont des techniques qu’il est possible d’utiliser pour captiver l'attention des gens. Ces techniques, listées ci-dessous, ont toutes pour but de rendre votre cerveau attentif en recréant ce que cette interaction pourrait être si cela vous arrivait en personne. Quand nous faisons cela, les informations sont plus faciles à comprendre et à se souvenir.

• 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 bien, mais c'est quelque chose de dur ou impossible à localiser. Les émotions comme la surprise et « je ne savais pas cela ! » pourraient être plus facile à intégrer.
• 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éos – L’utilisation des images et vidéos pour expliquer les choses en même temps que du texte n’est pas la seule façon d’aider en personne, c’est un moyen facile d'inclure les multiples styles d'apprentissage et la répétition.
• Activités – Il est bon de donner aux gens quelque chose d’utile à faire, particulièrement dans un tutoriel. C’est une chose de lire des instructions et de comprendre le processus, mais c’est souvent efficace de rappeler aux gens de tester les choses.

L’article Comment définir la page d’accueil est un bon exemple de l'utilisation de ces techniques.

Écrire une bonne introduction

Avec le titre et la table des matières, l’introduction est ce que les gens utilisent pour déterminer rapidement s’ils sont au bon endroit.

• Pour un tutoriel ou un article sur comment faire : donnez un bref résumé des choses qui peuvent être apprises.
• Pour un article de référence : donnez une brève explication de la fonctionnalité.
• Pour un article de résolution des problèmes : donnez un bref résumé du problème et de ses symptômes.

Une bonne introduction peut généralement servir de bon résumé. Souvent, vous pouvez juste la copier dans le champ « Résumé des résultats de recherche » et vous avez fini.

Organiser en pratique l'article

L’idée générale ici est d’essayer de construire des compétences de la plus simple à la plus complexe 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 en cas limite.

Utiliser des titres de paragraphe descriptifs

Nos articles sont généralement compréhensibles. Il est donc important d’utiliser des titres de paragraphe descriptifs pour aider les gens à trouver la partie de l'article dont ils ont besoin. Jetez un œil à votre table des matières. Est-ce que, couplé avec l'introduction, cela vous donne un bon aperçu du but de l’article ?

Rendre les instructions pas-à-pas faciles à suivre

La chose principale à garder à l’esprit lors de l’écriture d'instructions pas-à-pas est d’être attentif à l’inclusion de toutes les actions nécessaires pour la réalisation de la tâche. Si, par exemple, vous devez cliquer sur « OK » après la sélection d'une préférence afin d’aller à l’étape suivante, assurez-vous de mettre « cliquez sur OK » dans l'étape. Des choses supplémentaires sont à considérer :

• Il y a toujours plusieurs façons d’arriver à un résultat. Nous devrions toujours choisir la façon la plus conviviale : utilisation de l’interface utilisateur graphique et des menus quand c’est possible.
• Utilisez des phrases complètes en décrivant la manière d’accéder à l’interface utilisateur.
• Incluez les résultats attendus en donnant les instructions (par exemple, cliquez sur OK et la fenêtre se ferme.)

Voici un exemple extrait de l’article Comment définir la page d’accueil avec des explications entre parenthèses.

Définir un unique site web comme page d'accueil
(Le titre – ce que les étapes vont accomplir)

« Si vous aimez que les choses soient simples, voici un moyen de définir votre page d’accueil en trois étapes faciles »
(Contexte – montre une vue d’ensemble – pourquoi nous faisons cela)

1. Rendez-vous sur la page que vous désirez comme page d’accueil.
2. Cliquez sur l’icône à gauche de la barre de navigation et faites le glisser vers le bouton « Accueil », puis relâchez le clic souris.
3. Cliquez sur « Oui » pour confirmer.

Faites un essai : Cliquez sur le bouton « Accueil » et votre nouvelle page d'accueil se charge dans l’onglet en cours. Ce n’est pas plus compliqué que cela !
(Activité – donne une mission au lecteur et décrit le résultat attendu)

Les liens courts sont facultatifs

Nous avons un modèle pour ajouter un lien court mzl.la en bas d’un article, ceci afin de faciliter l’ajout de liens d’article dans les messages de l’Army of Awesome.

Si vous en ajoutez un à un article, assurez-vous que l’URL de l'article ne comprend pas la chaîne de la langue ou n’importe quel autre paramètre supplémentaire à la fin.

Par exemple, si vous chargez Update Firefox to the latest version, cela peut donner :

https://support.mozilla.org/en-US/kb/update-firefox-latest-version#os=win7&browser=fx20

Vous devez changer cela avant de le raccourcir :

https://support.mozilla.org/kb/update-firefox-latest-version

Pour créer un lien mzl.la :

1. Collez le lien vers un article dans le champ de rétrécissement sur https://bitly.com.
2. Modifiez le lien comme décrit ci-dessus.
3. Cliquez sur le bouton Shorten
4. Cliquez sur le bouton Copy sur la page générée.

Guide de style SUMO

Comme nous en avons parlé plus tôt, nous devrions utiliser un style conversationnel et actif comme si vous parliez en personne avec quelqu’un. Donc vous devriez éviter de dire des choses comme « si les marque-pages d’un utilisateur sont perdus… » et dire plutôt « Si vous avez perdu vos marque-pages… » Voici d'autres problèmes courants de style que vous pouvez rencontrer en écrivant des articles d'assistance :

Toujours utiliser les termes de la manière dont ils apparaissent dans l'interface de Firefox. Par exemple :

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

Termes informatiques généraux :

• Internet a une majuscule.
• Website en un seul mot.
• Log in et log out sont des verbes, par exemple, « Log in to the website. »
• Login et logout sont des noms (généralement utilisés comme des adjectifs), par 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 devraient pas contenir la langue :

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

Mettez la première lettre en majuscule des éléments suivants :

• Les noms propres
• Le premier mot d'une phrase complète
• Les lettres des abréviations et acronymes sauf s'ils sont normalement en minuscules
• Le premier mot dans les listes numérotées et à puces
• Le nom d’une touche sur le clavier
• Le premier mot d’une phrase complète suivant les deux-points
• Le premier mot d’un titre de paragraphe ou d'article

Dans un souci de clarté, n'utilisez pas i.e. et e.g..

Nous avons des styles visuels spéciaux pour un nombre d'éléments qui peuvent être réalisés en ajoutant la balise wiki autour de l'élément (consultez l’article Mémo pour la syntaxe wiki de SUMO pour les styles les plus courants).

Nous avons une balise wiki spéciale – {for} – qui vous permet de cibler les informations pour les versions spécifiques de Firefox ou de systèmes d’exploitation. Par exemple, vous affichez un jeu d'instructions aux gens exécutant Windows et un autre aux gens utilisant Mac OS X (consultez l’article Comment utiliser les balises « for » pour les détails).