Documentation/Style guide/fr

Vue d'ensemble
Cette page est un guide de style supplémentaire pour écrire et modifier la documentation technique dans MediaWiki ainsi que d'autres espaces techniques. It is intended to provide tips for writing clear, concise technical documentation in plain language, to highlight best practices and standards for a variety of technical documents used across projects, to share resources and knowledge about technical writing and editing in general.

La bonne documentation technique rend plus faciles les contributions techniques de chacun dans tous les projets Wikimedia. 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 certains sujets en détail (comme la ponctuation) et résume les points-clés pour les autres. It can be a useful reference for anyone writing or editing technical documentation in English across Wikimedia projects when no more specific guidelines exist on the local wiki.

Règles supplémentaires pour l'écriture et les modifications techniques
It is important to follow clear standards and style guidelines for writing and editing documentation, especially when many individuals contribute to it with varying levels of skills and experience. There are many style and usage rules for general writing – far too many to remember – and even more for technical writing. This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.

Ecrire pour un auditoire technique
Avant de commencer à écrire, il est important de penser à l'auditoire qui sera concerné par votre travail.


 * Qui à votre avis 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 ?

Once you have an understanding of your audience, you will have a better sense of what you need to convey and how to convey it.

Ecrire avec 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
When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing. Votre communication s'insère dans le contexte d'une situation plus grande. The context may be bounded by the era you are writing in, the type of technology available, your geographical location and culture, or the current culture and communication styles of the community you and your readers belong to. The occasion may be personal and arise from the situation that motivated you to create or improve a piece of documentation.

For example, if you are writing technical documentation for Wikimedia projects, consider the culture created by the individuals who volunteer, and take part across them. How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

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. Naturally, this audience should play a critical role in how the documentation is shaped and reshaped. Think about ways you can gather information about your users' experiences. 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 ?

Clareté et cohérence
Your goal is to make accessing, reading, and creating technical documentation for MediaWiki/Wikimedia easier and more intuitive by promoting clarity and consistency throughout. 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. This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

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.

Language
This section briefly mentions some topics worth exploring elsewhere in more detail. Always check your words and expressions against these criteria on Wiktionary: 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.

Plain English
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.

Tips:


 * Avoid ambiguity, jargon, and vague or complex wording.
 * Use words your audience will understand, and enough words to convey your message.
 * Define terms that may not be obvious to individuals who are new to the subject matter you are writing about.
 * Keep paragraphs and sentences short and concise.
 * Use contractions or don't. Be consistent.

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

Consider using these elements in your writing:

Point of view

 * Use second person ("You" or assumed "You") when addressing your audience.
 * Avoid first person ("I"), 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.

Overview
All pages should include an overview section that explains:


 * 1) Purpose of the page
 * 2) Audience of the page
 * 3) Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
 * 4) Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
 * 5) Use case, case study, a practical understanding of the product, service or tool in action. (optional)

Table of contents

 * Each page should include a table of contents, so information can be accessed easily.

Titles and headers

 * Use sentence case for headers.
 * Keep header fonts consistent throughout documentation.
 * Optional use of anchors to link sections or subsections in the same page.

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
Many situations call for text to be formatted in a way that 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:


 * ApiEx for api.php request URLs
 * Api help to transclude generated API documentation
 * caution, fixtext, note, tip, todo, and warning for styles of inline highlight boxes
 * fixme, historical, notice, outdated, and update for page/section message boxes
 * class doclink, file doclink, and js doclink to link to MediaWiki core's generated documentation
 * git file to link to source code
 * for IRC link
 * Key press for, e.g. Ctrl, and button for, e.g.
 * main and see also for page/section hatnotes (a short note placed at the top of an article)
 * MW file for a box with info and links for a file in MediaWiki core
 * ptag for the top-right-of-page phabricator project tag
 * tracked for the related Phabricator task
 * RestOfVariableName for global variables
 * tag for a quick way to mention an XML-style tag in a preformatted way

Traductions
All pages on mediawiki.org are candidates for translation into multiple languages. 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
 * Technical documentation prioritization

Voir aussi

 * Web APIs hub/Contributing – guide to writing articles for third-party developers
 * Some other technical documentation style guides:
 * Rackspace Style Guide
 * Gnome Documentation Style Guide
 * Google Developer Documentation Style Guide
 * Wordpress Documentation Style Guide
 * Technical writing