Guide de style
Présentation
Ce guide de style donne les indications pour écrire et modifier la documentation technique dans MediaWiki et autres espaces techniques. Il fournit des conseils pour vous aider à écrire de manière claire et concise la documentation technique en langue simple. Il donne également des liens vers des ressources complémentaires concernant l'écriture technique et les modifications en général.
Une bonne documentation technique rend plus facile la contribution des utilisateurs dans les projets Wikimedia. Il est important de suivre des normes claires et des règles de styles pour l'écriture et la modification de la documentation, particulièrement lorsque les participants ont des niveaux différents de connaissance et d'expérience. Que vous vous considériez écrivain ou pas, vos contributions seront nécessaires et appréciées.
Manuel de style de la Wikipedia anglophone
Le manuel de style de la Wikipedia anglophone couvre en détail les sujets généraux concernant l'écriture (comme la ponctuation) et résume les points-clés des autres guides de style. Cela peut être une référence utile pour quiconque écrit ou modifie de la documentation technique en anglais pour les projets Wikimedia, particulièrement lorsqu'il n'existe pas d'autre guide sur le wiki local.
Cette page fournit les indications de base et les conseils pour vous aider à commencer avec la documentation technique. Elle comprend des informations spécifiques à la documentation technique qui ne se trouvent pas dans le Manuel de style de Wikipedia.
Audience et contenu
Ecrire pour un auditoire technique
Avant de commencer à écrire, évaluez l'auditoire concerné par votre travail, c'est à dire les personnes auxquelles vous adressez votre travail :
- Qui va lire cette documentation technique ?
- Quel sera le degré de comptétence des auditeurs sur le sujet ?
- Seront-ils familiers avec les concepts que vous allez présenter ?
- Que faudrait-il qu'il connaissent afin de comprendre le sujet ?
Une fois que vous avez cerné quel sera votre auditoire, vous aurez une meilleure idée de ce qu'il vous faudra pour communiquer.
- Si vous savez que votre auditoire est très technique et familier avec le processus que vous décrivez, alors vous n'avez pas à réexpliquer les principes de base.
- Si vous savez que votre auditoire est en formation ou n'est pas familier avec le processus que vous décrivez, alors mettez des explications sur les concepts de base et insérez des liens vers les informations supplémentaires.
Ecrire en ayant un but
A quoi va servir votre documentation technique ? Il y a beaucoup de raisons pour écrire de la documentation. Avant de commencer, il est utile que vous sachiez pourquoi vous allez écrire et dans quel but.
- Est-ce que c'est pour former des utilisateurs, comme les débutants, à propos d'un processus ou d'un concept ?
- Est-ce que c'est pour indiquer la manière de suivre un processus ?
- Est-ce c'est pour fournir des connaissances de base et un contexte pour un concept ou un processus ?
- Est-ce que vous indiquez une référence dans le but de fournir des informations ?
Ecrire dans un contexte
Quand vous vous déciderez sur ce qu'il faut écrire et comment le présenter pour vos lecteurs, il peut vous aider à définir un contexte ou être une occasion d'écrire. Votre communication s'insère dans le contexte d'une situation plus grande. Le contexte peut être lié à l'époque à laquelle vous écrivez, le type de technologie disponible, votre situation géographique et votre culture, ou la culture actuelle et les manières de communiquer de vos lecteurs. L'occasion peut être personnelle et venir de la situation qui vous a motivé pour créer ou améliorer un élément de documentation.
Par exemple, si vous écrivez de la documentation technique pour les projets Wikimedia, respectez la culture créée par les contributeurs de ces projets. Comment positionner au mieux vos écrits dans le contexte de cette communauté et de sa culture pour créer la documentation technique la plus significative et la plus utile ?
Tests des utilisateurs et retours
Créer de la documentation technique pour communiquer des idées et des concepts à un auditoire réel composé d'utilisateurs. Naturellement, cet auditoire doit pouvoir avoir un rôle critique sur la manière dont la documentation est mise en forme et retravaillée. Pensez aux manières de récupérer des informations au sujet de l'expérience de vos utilisateurs. Prenez quelques instants pour répondre aux questions suivantes :
- Est-ce qu'il existe un mécanisme pour prendre en compte les remarques en retour ?
- Pouvez-vous prendre en charge des conversations limitées avec l'auditoire afin d'apporter des améliorations ?
- Pouvez-vous utiliser les forums tels que Stack Overflow ou les listes de diffusion pour voir si votre document répond aux questions les plus fréquentes que les utilisateurs ont à propos de votre sujet particulier ?
Clareté et cohérence
La clareté et la cohérence rendent l'accès, la lecture et la création de la documentation technique plus faciles sur tous les projets MediaWiki/Wikimedia. La documentation technique est écrite pour un large auditoire et reste modifiable par une variété de contributeurs.
La voix, le ton, l'usage grammatical, le style et le format, doivent être cohérents à travers la documentation technique ainsi que les ensembles de contenus similaires. Ceci aide les lecteurs à apprendre la navigation au travers de l'information et la faciliter pour que les contributeurs puissent comprendre comment modifier et ajouter de nouvelles informations.
Décider du type de document
Identifiez d'abord votre audience principale, le sujet et le contexte, afin de décider du type de document que vous allez créer.
| Exemple d'auditoire | But[1] | Types de documents potentiels | Exemple |
|---|---|---|---|
| Débutant cherchant à apprendre comment devenir un utilisateur de Toolforge | apprendre | tutoriels, FAQ, guides pour commencer | les FAQ de Cloud VPS et de Toolforge |
| Contributeur expérimenté techniquement cherchant à analyser un problème connu | atteindre un objectif | présentations générales et guides How-To | mon premier outil Flask OAuth |
| Personne cherchant à comprendre l'historique de ORES et la manière dont il a évolué | comprendre | article explicatif, billet de blog, « résumés » | le service d'intelligence artificielle ORES donne aux Wikipédiens les pouvoirs des rayons X permettant de voir les modifications erronnées |
| Personne cherchant la définition des clés SSH | s'informer | les guides de référence, les glossaires | glossaire |
Langue
Cette section mentionne brièvement quelques points que vous pouvez approfondir en détail à votre guise.
Comparez toujours les mots et les expressions que vous utilisez avec les critères définis dans le Wiktionnaire :
Les entrées de Wiktionary couvrent des centaines de langues, décrivent explicitement les fonctions grammaticales et lexicales des mots et leurs déclinaisons, fournissent des étiquettes de contexte détaillées (y compris les termes de jargon, en anglais UK et en anglais américain) et montrent l'équivalent des mots traductibles dans les centaines d'autres langues.
Anglais simple
Rappelez-vous que pour beaucoup de visiteurs qui viennent sur ces pages, l'anglais n'est pas leur langue maternelle.
Pour la documentation écrite en anglais, l'anglais brut (aussi appelé langue directe) est ce qu'il y a de mieux. L'écriture claire est la plus compréhensible par divers auditoires et également la plus facile à traduire. Vous trouverez dans les Actualités techniques concernant les règles d'écriture sur Meta-Wiki plusieurs bon outils pour vérifier votre texte.
- Evitez les ambiguités, le jargon, et le texte vague ou complexe.
- Utilisez des mots que votre auditoire comprendra et suffisamment de mots pour exprimer votre message.
- Définissez les termes qui ne semblent pas évidents à comprendre pour les personnes qui sont nouvelles sur le sujet à propos duquel vous écrivez.
- Garder les paragraphes et les phrases courtes et concises.
- Utilisez les formes contractées ou pas, mais soyez cohérent.
Voix et ton
MediaWiki est un endroit que chacun peut mettre à jour. Ainsi il peut être difficile de maintenir une voix et un ton cohérent tout au long de la documentation.
Prenez en compte les éléments suivant pour votre écriture :
| Discours et ton | Signification | Au lieu de | Utilisez plutôt |
|---|---|---|---|
| Amical | La documentation technique ne doit pas paraître académique ni abrupte. Ecrivez pour votre auditoire comme s'il était en face de vous, en personne. | Avant de commencer, l'utilisateur doit créer un compte. | Commencez par créer un compte. |
| Professionnel | La documentation technique peut être amicale mais doit rester professionnelle. Utilisez Langage inclusif. | Ne faites pas un milliard de changements. | Essayez de faire un minimum de corrections. |
| Positif | Evitez d'utiliser des phrases négatives. Expliquez les choses en fonction de ce qu'il y a à faire. Il est plus difficile d'analyser mentalement une phrase complexe négative ! | N ne se produira pas si vous ne faites pas XYZ. | Pour provoquer N, faites XYZ. |
| Actif | Essayez d'utiliser la forme active, sauf quand la diplomatie demande à employer la forme passive. | L'extension doit être enregistrée. | Vous devez enregistrer l'extension. |
| Sans genre | Adoptez un langage inclusif du genre. Assurez-vous que votre auditoire englobe toutes les identités de genres. | Quand il appuie sur Enregistrer | Quand l'utilisateur appuie sur Enregistrer |
| Inclusif | Utilisez des alternatives aux mots communs ou aux phrases qui pourraient involontairement renforcer les stéréotypes inappropriés. | Cet interface utilisateur est affreux. | Cet interface utilisateur pourrait être améliorée. |
| Pas de frustration | Evitez les termes tels que facile ou simple qui peuvent être frustrant pour les personnes moins avancées techniquement sur le sujet. | Créez simplement un compte utilisateur. | Créez un compte utilisateur. |
| Pas d'expressions familières | Il peut être troublant d'utiliser des expressions familières, des blagues, des jeux de mots, ou des tournures de phrase que les utilisateurs dont l'anglais n'est pas la langue maternelle ou ceux d'autres régions, ne pourraient pas comprendre facilement. | Créer un compte utilisateur, c'est du gâteau. | La création du compte utilisateur se fait en deux temps. |
Point de vue
- Utilisez la seconde personne du pluriel ("vous", ou pensez "vous") lorsque vous vous adressez à votre auditoire.
- Evitez la première personne ("je" ou "nous"), à moins que vous écriviez une FAQ avec des questions écrites à la première personne.
- Utilisez le mode impératif dans la plupart des documents qui concernent des objectifs ou des processus.
Les dates
- Utilisez toujours l'année complète sur 4 digits.
- Utilisez les dates absolues (en mai 2037) plutôt que les dates relatives (l'année prochaine en mai).
- Evitez d'ajouter des dates à réactualiser manuellement. Par exemple : écrivez
{{#time: Y }}au lieu de 2024 s'il s'agit de l'année courante, peu importe de quelle année il s'agit.
Structurer les pages
Aperçu général
Toutes les pages doivent contenir une section d'introduction (appelée également section principale) qui explique :
- le sujet de la page
- l'auditoire concerné par la page
- les prérequis que le lecteur doit avoir avant de commencer (par exemple une connaissance pratique de Python)
- Logiciels ou outils dont le lecteur aura besoin pour finaliser le processus ou les tâches indiquées sur la page (par exemple, que Java soit installé)
- Cas utilisateur, étude de cas, comprendre le produit, le service, ou l'outil en action du côté pratique. (facultatif)
Sommaire
- Chaque page doit inclure un sommaire pour pouvoir accéder rapidement à l'information.
Titres et entêtes
- Utilisez la casse des phrases dans les entêtes.
- Gardez cohérente la police des entêtes tout au long du document.
- L'utilisation des ancres (anchors) est facultative; elles servent à référencer des sections ou des sous-sections à l'intérieur d'une même page.
- Ajoutez un saut de ligne après les entêtes de section. Cela impacte la manière dont le contenu est formaté pour la traduction.
- Ne mettez pas d'entête avant la section de présentation générale ou la section principale.
Flux d'information
Les pages de documentation technique doivent suivre un modèle cohérent au travers des collections de contenu.
Un modèle idéal de page pourrait être :
- Titre de la page
- Introduction / Description générale
- Entête
- Contenu
- Sous-section si nécessaire
- Contenu
- Sous-section si nécessaire
- Contenu
Formatage du texte
Formatage d'exemples de code et d'autres éléments techniques
La mise en forme différencie le code ainsi que les éléments techniques, du texte régulier.
| Purpose | Wiki-Markup | Result | Situation |
|---|---|---|---|
| Code | <code>code</code>
|
code
|
Use for short strings of code, including wikitext markup.
Within |
| Syntax highlight |
<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>
Text before |
.citation {
margin: 0;
}
Text before |
Use the <syntaxhighlight lang="...">...</syntaxhighlight> tag to document a few lines of code, and preserve whitespace and linebreaks. The inline attribute allows using it within an existing paragraph.
Note you cannot use italic in the middle of a See Extension:SyntaxHighlight for more details. |
| Preformatted | <pre>preformatted text
|
preformatted text
with indent
|
Same as above (preserve whitespace and linebreaks), but without coloring. |
| Keyboard input | <kbd>keyboard 123</kbd> (vs keyboard 123)
|
keyboard 123 (vs keyboard 123) | Use <kbd>...</kbd> for actual keyboard input - the text a user types into an input field or at a terminal command line. It displays in plain monospace.
|
| Variables | <var>variable</var>
''italics''
|
variable
italics |
Use italics for variables like message-key-name and sample names like My page title.
Do not use punctuation such as <YOURPASSWORD>, because readers don't know the angle brackets are noise and will type them. |
| Bold | '''bold'''
|
bold | Generally only used for the first instance of the page-title, and for rare emphasis of keywords to enable easier skimming of lists or paragraphs.
Sometimes bold is overused for emphasis. You may consider using a template instead, e.g. {{Caution}}, {{Note}}, or {{Warning/core}}.
|
| Quotations | "quotation marks"
Text before
Text after |
"quotation marks"
Text beforeText after |
Use quotation marks for brief pieces of content quoted from other sources.
Use blockquote for longer pieces of content. |
| Abbreviations | JavaScript (JS)
|
JavaScript (JS)
JS |
You should define abbreviations the first time they are used. Use either plain text and parentheses, or the HTML abbr tag. |
| Keypress | {{Key press}}
|
Ctrl+⇧ Shift+I | Showing specific keyboard presses or combinations. Extensive examples in Éditeur Visuel/Portail/Raccourcis clavier.
Note: This template might not exist on other wikis. |
| Button | {{Button}}
|
Prévisualiser | Showing UI buttons that need to be clicked on.
Note: This template might not exist on other wikis. |
Liens
| Type de lien | Objet | Implémentation | Exemple |
|---|---|---|---|
| Local | Lien vers d'autres pages MediaWiki |
|
MediaWiki |
| Cible traduite | Lien vers d'autres pages traduites MediaWiki | [[Special:MyLanguage/Foo|Foo]]
|
Comment contribuer |
| Interwiki | Lien vers une page qui appartient à un projet Wikimedia différent |
|
Page de documentation sur Wikipedia |
| Externe | Lien vers des pages externes | [https://www.example.org Example.org]
|
Example |
Modèles
Les modèles sont souvent utilisés sur les pages de MediaWiki.org .
Les modèles aident à maintenir une certaine cohérence et à rendre l'information plus facile à traduire.
Vous trouverez ci-dessous quelques modèles communs.
Modèles pour formater une page
- {{Caution}}, {{Fixtext}}, {{Note}}, {{Tip}}, {{Todo}}, {{Warning/core}} - styles de mise en valeur des boîtes en ligne
- {{Fixme}}, {{Historical}}, {{Notice}}, {{Obsolète}}, {{Update}} - boîtes de message des pages ou des sections
- {{Main}}, {{See also}} - notes d'entête des pages ou des sections (courte information placée au début d'un article)
Modèles pour le noyau MediaWiki et les sources Git
- {{Class doclink}}, {{File doclink}}, {{Js doclink}} - lien vers la documentation générée du noyau MediaWiki
- {{MW file}} - boîte d'information avec lien vers un fichier du noyau MediaWiki
- {{Git file}} - crée un lien vers le code source
Modèles pour Phabricator
- {{Ptag/fr}} - balise de projet Phabricator, bord supérieur droit de la page
- {{Tracked}} - lien vers la tâche Phabricator associée à l'article
Autres modèles utiles
- {{irc|wikimedia-tech}} - lien IRC
- {{Key press}} - représente des touches comme Ctrl+⇧ Shift+I, et {{Button}} représente un bouton comme Prévisualiser
- {{ApiEx}} - pour les URLs de requête api.php
- {{Aide sur l'API}} - pour transclure la documentation générée de API
- {{Wg}} - variables globales
- {{Tag}} - représente rapidement une balise de style XML de manière préformatée
Traductions
Toutes les pages de mediawiki.org sont candidates à la traduction dans plusieurs langues. MediaWiki.org est un wiki multilingue qui utilise l'extension Translate pour présenter des traductions alternatives et pour gérer la traduction des pages.
- Si une page a été traduite, cliquez sur 'Modifer le source' pour modifier la page entière. Les marqueurs de balises de traduction mal placés autour des titres de section peuvent perturber la modification des sections, car depuis juillet 2015 l'Editeur Visuel ne comprend pas les balises suivantes :
<languages>,<translate>,<tvar> - Ne copiez pas, ni ne collez pas le balisage existant. Si vous avez un doute, concentrez-vous sur l'écriture d'un bon texte et laissez une autre personne implémenter le balisage pour la traduction.
Voir aussi
- Quelques autres guides de style concernant la documentation technique :
- Wikiversity:Technical writing
- Autres ressources liées aux langues :