Documentation/Style guide/fr

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.

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.

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.

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, anglais brut 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.

Voix et intonation
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 :

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  au lieu de  s'il s'agit de l'année courante, peu importe de quelle année il s'agit.

Aperçu général
Toutes les pages doivent contenir une section d'introduction (appelée également section principale) qui explique :


 * 1) le sujet de la page
 * 2) l'auditoire concerné par la page
 * 3) les prérequis que le lecteur doit avoir avant de commencer (par exemple une connaissance pratique de Python)
 * 4) 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é)
 * 5) 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

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.

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 - styles de mise en valeur des boîtes en ligne
 * fixme, historical, notice, outdated, update - boîtes de message des pages ou des sections
 * main, see also - for page/section hatnotes (a short note placed at the top of an article)

Modèles pour le noyau MediaWiki et les sources Git

 * class doclink, file doclink, js doclink - to link to MediaWiki core's generated documentation
 * MW file - for a box with info and links for a file in MediaWiki core
 * git file - crée un lien vers le code source

Modèles pour Phabricator

 * ptag - for the top-right-of-page Phabricator project tag
 * tracked - for the related Phabricator task

Autres modèles utiles

 * - lien IRC
 * Key press - pour représenter des touches comme Ctrl, et button pour représenter un bouton commme
 * ApiEx - for api.php request URLs
 * Api help - to transclude generated API documentation
 * RestOfVariableName - for global variables
 * tag - for a quick way to mention an XML-style tag in a preformatted way

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.

Informations supplémentaires

 * Documentation/Technical writer guide
 * Documentation/Technical documentation prioritization

Voir aussi

 * Quelques autres guides de style concernant la documentation technique :
 * guide de style pour la documentation de développement de Google
 * Guide de style pour l'écriture de documents web MDN
 * Technical writing
 * Autres ressources liées aux langues :
 * liste de mots
 * Naming things
 * Naming things