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. __TOC__ ==Pour qui écrivons-nous les articles ?== 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== Quand nous choisissons un titre pour un article, nous voulons essayer de le faire correspondre à ce que les gens recherchent et explorent. les utilisateurs doivent être en mesure de reconnaître le sujet de l'article afin de cliquer en toute confiance. Il ne devrait pas dépasser 70 caractères, le suffixe de sa catégorie et Assistance de Mozilla compris. Voici des exemples de types de titres que vous devriez choisir : *Pour un tutoriel ou un article sur comment faire : Parvenir à ce résultat (p.ex., Comment définir la page d'accueil) *Pour un article de référence : Nom de la fonctionnalité – but principal (p.ex, Onglets épinglés – garder vos sites web favoris ouverts à portée d'un clic) *Pour un article de résolution des problèmes : C'est le problème que je suis en train d'avoir – comment le corriger (p.ex., Les sites web ne se chargent pas – investiguer et corriger les messages d'erreur) Éviter d'utiliser les gérondifs (-ing en anglais). == Corriger l'identifiant == L'identifiant (traduction de « slug ») est une partie de l'URL de l'article, comme : http://support.mozilla<!-- -->.org/fr/kb/ceci-est-identifiant. Il ne devrait pas dépasser 50 caractères. À partir de l'identifiant auto-généré, vous pouvez supprimer les [http://fr.wikipedia.org/wiki/Mot_vide mots vides] et autres mots non nécessaires. Assurez-vous néanmoins qu'il a du sens et contient les informations importantes. == Sélectionner ses catégories, produits et sujets == Un article d'aide décrit soit comment faire une chose, soit comment résoudre un problème. Sélectionnez également le ou les produits et le ou les sujets auxquels il s'applique. == Choisir des mots-clés pertinents == Un article doit être facilement trouvable. C'est le rôle des mots-clés. Tous les mots dans le titre qui ne sont pas des mots vides tel que « the » et « is » sont déjà considérés comme des mots-clés. Ne les ajoutez donc pas comme mot-clé. Pour les mots-clés, choisissez des synonymes, des termes apparentés, des versions régionales (britannique), des fautes de frappe habituelles. N'ajoutez PAS trop de mots-clés car chacun d'entre eux aura moins de poids. Pour plus d'info, consultez [[Keywords Field - Authoring KB Articles]]. * Les mots-clés pour « How to set the home page » devraient être au minimum start et homepage. * Pour « How to use bookmarks to save and organize your favorite websites », favourite est suffisant. * L'article « Clear the cache - Delete temporary Internet files to fix common website issues » peut avoir cash comme mot-clé. == Rédiger le résumé == Lorsque vous rédigez le résumé, essayez d'expliquer le but de l'article en étant le plus concis possible. Il ne devrait pas dépasser 160 caractères afin qu'il soit affiché en entier dans les résultats de recherche Google. ==Techniques pour 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ù les unicornes utiliseront leurs pouvoirs arc-en-ciel pour devenir des bougies magiques qui, une fois consumées, vous fera devenir un ninja d'ordinateur de niveau 70. Êtes-vous réveillé maintenant ? Bien. Ce paragraphe semble un peu ennuyeux, au moins jusqu'à ce les unicornes apparaissent. L'utilisation de l'humour et des émotions (SURPRISE !) sont des techniques que nous pouvons utiliser pour captiver l'attention des gens. Ces techniques, que j'ai 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 [[How to set the home page]] 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. ==Comment organiser 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. ==Comment 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, c'est à dire l'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 (c.-à-d., cliquez sur OK et la fenêtre se ferme.) Voici un exemple extrait de l'article [[How to set the home page]] avec des explications entre parenthèses. <br><br>'''Définir un unique site web comme page d'accueil''' <br> (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''<br> (Contexte - montre une vue d'ensemble - pourquoi nous faisons cela) # Rendez-vous sur la page que vous désirez comme page d'accueil. # 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. # Cliquez sur « Oui » pour confirmer. <br>'''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 ! <br> (Activité – donne une mission au lecteur et décrit le résultat attendu) == Guide de style SUMO == Comme nous en avons parler 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 informatique généraux :''' *Internet a sa première lettre en majuscule. *Website en un seul mot. *Log in et log out sont des verbes, p.ex., « Log in to the website. » *Login et logout sont des noms (généralement utilisés comme des adjectifs), .p.ex, « 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 '''Titres et sections''' Notre Wiki est affiché en utilisant HTML5 qui utilise l'élément <nowiki><section></nowiki>. Vous pouvez utiliser l'élément <nowiki><section></nowiki> autour d'un contenu lié. Ce que cela signifie pour les titres est que chaque section peut avoir son propre résumé au début avec un titre de niveau h1. '''Dans un souci de clarté, évitez l'utilisation d'i.e et e.g. Si vous devez les utiliser, [http://theoatmeal.com/comics/ie voici une explication sympa en anglais] de comment cela fonctionne.''' '''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 [[Markup chart]] pour une liste complète).''' *{note}Note{/note} *{warning}Avertissement{/warning} *<code>Code</code> *{filepath Noms de fichier} et {filepath chemin/fichier} *Raccourcis clavier comme {key Ctrl+T} *Menus – {menu Firefox} *{button Boutons} '''Nous avons une balise Wiki spéciale – <nowiki>{</nowiki>for<nowiki>}</nowiki> – 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 [[How to use For]] pour les détails).

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.

Pour qui écrivons-nous les articles ?

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

Quand nous choisissons un titre pour un article, nous voulons essayer de le faire correspondre à ce que les gens recherchent et explorent. les utilisateurs doivent être en mesure de reconnaître le sujet de l'article afin de cliquer en toute confiance. Il ne devrait pas dépasser 70 caractères, le suffixe de sa catégorie et Assistance de Mozilla compris. Voici des exemples de types de titres que vous devriez choisir :

• Pour un tutoriel ou un article sur comment faire : Parvenir à ce résultat (p.ex., Comment définir la page d'accueil)
• Pour un article de référence : Nom de la fonctionnalité – but principal (p.ex, Onglets épinglés – garder vos sites web favoris ouverts à portée d'un clic)
• Pour un article de résolution des problèmes : C'est le problème que je suis en train d'avoir – comment le corriger (p.ex., Les sites web ne se chargent pas – investiguer et corriger les messages d'erreur)

Éviter d'utiliser les gérondifs (-ing en anglais).

Corriger l'identifiant

L'identifiant (traduction de « slug ») est une partie de l'URL de l'article, comme : http://support.mozilla.org/fr/kb/ceci-est-identifiant. Il ne devrait pas dépasser 50 caractères. À partir de l'identifiant auto-généré, vous pouvez supprimer les mots vides et autres mots non nécessaires. Assurez-vous néanmoins qu'il a du sens et contient les informations importantes.

Sélectionner ses catégories, produits et sujets

Un article d'aide décrit soit comment faire une chose, soit comment résoudre un problème. Sélectionnez également le ou les produits et le ou les sujets auxquels il s'applique.

Choisir des mots-clés pertinents

Un article doit être facilement trouvable. C'est le rôle des mots-clés. Tous les mots dans le titre qui ne sont pas des mots vides tel que « the » et « is » sont déjà considérés comme des mots-clés. Ne les ajoutez donc pas comme mot-clé. Pour les mots-clés, choisissez des synonymes, des termes apparentés, des versions régionales (britannique), des fautes de frappe habituelles. N'ajoutez PAS trop de mots-clés car chacun d'entre eux aura moins de poids. Pour plus d'info, consultez Quand et comment utiliser les mots-clés pour améliorer le classement de recherche d’un article.

• Les mots-clés pour « How to set the home page » devraient être au minimum start et homepage.
• Pour « How to use bookmarks to save and organize your favorite websites », favourite est suffisant.
• L'article « Clear the cache - Delete temporary Internet files to fix common website issues » peut avoir cash comme mot-clé.

Rédiger le résumé

Lorsque vous rédigez le résumé, essayez d'expliquer le but de l'article en étant le plus concis possible. Il ne devrait pas dépasser 160 caractères afin qu'il soit affiché en entier dans les résultats de recherche Google.

Techniques pour 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ù les unicornes utiliseront leurs pouvoirs arc-en-ciel pour devenir des bougies magiques qui, une fois consumées, vous fera devenir un ninja d'ordinateur de niveau 70.

Êtes-vous réveillé maintenant ? Bien.

Ce paragraphe semble un peu ennuyeux, au moins jusqu'à ce les unicornes apparaissent. L'utilisation de l'humour et des émotions (SURPRISE !) sont des techniques que nous pouvons utiliser pour captiver l'attention des gens. Ces techniques, que j'ai 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.

Comment organiser 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.

Comment 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, c'est à dire l'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 (c.-à-d., 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)

Guide de style SUMO

Comme nous en avons parler 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 informatique généraux :

• Internet a sa première lettre en majuscule.
• Website en un seul mot.
• Log in et log out sont des verbes, p.ex., « Log in to the website. »
• Login et logout sont des noms (généralement utilisés comme des adjectifs), .p.ex, « 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

Titres et sections Notre Wiki est affiché en utilisant HTML5 qui utilise l'élément <section>. Vous pouvez utiliser l'élément <section> autour d'un contenu lié. Ce que cela signifie pour les titres est que chaque section peut avoir son propre résumé au début avec un titre de niveau h1.

Dans un souci de clarté, évitez l'utilisation d'i.e et e.g. Si vous devez les utiliser, voici une explication sympa en anglais de comment cela fonctionne.

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 Tableau de balisage pour une liste complète).

• Note
• Avertissement
• Code
• Noms de fichier et chemin/fichier
• Raccourcis clavier comme Ctrl + T
• Menus – Firefox
• Boutons

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 Comment utiliser les balises « for » pour les détails).