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 :


 * 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 : Wiktionary entries cover hundreds of languages, explicitly state the grammatical and lexical features of words and their declensions, provide detailed context labels (including about jargon, UK vs. USA English) and expose how translatable terms are in hundreds of other languages.

Anglais simple
Please remember: many visitors to these pages are not native English speakers.

For documentation written in English, Plain English works best. Clear writing is the most understandable by diverse audiences, and is also easiest to translate. There are a number of good tools for checking your writing, at Tech News' Writing Guidelines on Meta-Wiki.

Voix et intonation
MediaWiki is a place where anyone can edit. Thus, it can be difficult to maintain a consistent voice and tone in the documentation.

Prenez en compte les éléments suivant pour votre écriture :

Point de vue

 * Use second person ("You" or assumed "You") when addressing your audience.
 * Avoid first person ("I" or "we"), unless you are writing a FAQ with questions asked from the first person perspective.
 * Use an imperative mood for most documentation focused on goals or process.

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).
 * Avoid adding dates that will require regular manual updates. Example: Write  instead of  when referring to the current year, no matter what year it is currently.

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) Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
 * 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.
 * Add a blank line after section headers. This impacts how the content is packaged for translation.
 * Ne mettez pas d'entête avant la section de présentation générale ou la section principale.

Information flow
Technical documentation pages should follow a consistent pattern across content collections.

An ideal pattern for each page might be:
 * Page title
 * Introduction/Overview
 * Header
 * Content
 * Subhead if needed
 * Content

Formatting code examples and other technical elements
Formatting distinguishes code and other technical elements from regular text.

Modèles
Templates are often used on MediaWiki.org pages. Templates can help to maintain consistency and can make it easier to translate information.

Below are some common templates.

Templates for page formatting

 * caution, fixtext, note, tip, todo, and warning for styles of inline highlight boxes
 * fixme, historical, notice, outdated, and update for page/section message boxes
 * main and see also for page/section hatnotes (a short note placed at the top of an article)

Templates for MediaWiki core and Git source

 * class doclink, file doclink, and 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 to link to source code

Templates for Phabricator

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

Other useful templates

 * for IRC link
 * Key press for, e.g. Ctrl, and button for, e.g.
 * 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 is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of 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
 * MDN Web Docs Writing Style Guide
 * Technical writing
 * Autres ressources liées aux langues :
 * liste de mots
 * Naming things
 * Naming things