Documentation/Guide de style

This page is a translated version of the page Documentation/Style guide and the translation is 100% complete.
Other languages:
Bahasa Indonesia • ‎English • ‎Türkçe • ‎français • ‎polski • ‎中文 • ‎日本語

Présentation

Cette page est un guide de style supplémentaire pour écrire et modifier la documentation technique dans MediaWiki ainsi que d'autres espaces techniques. Le but est de fournir des conseils pour écrire de manière claire et concise la documentation technique en langue brute, pour indiquer les meilleures pratiques et les standards pour une variété de documents techniques utilisés sur les projets, pour partager les ressources et la connaissance à propos de l'écriture technique et des modifications en général.

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. Cela peut être une référence utile pour quiconque écrit ou modifie de la documentation technique en anglais pour les projets Wikimedia, lorsqu'il n'existe pas de guide sur le wiki local.

Règles supplémentaires pour l'écriture et les modifications techniques

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 plusieurs personnes participent en même temps avec différents niveaux de connaissance et d'expérience. Il existe beaucoup de règles de style et d'usage pour l'écriture en général - même trop pour que l'on puisse s'en souvenir - et encore davantage pour l'écriture technique. Cette page fournit les indications de base et les conseils pour vous aider à commencer, ainsi que quelques informations spécifiques qui ne se trouvent pas dans le Manuel de style de Wikipedia.

Audience et contenu

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 ?

Une fois que vous avez cerné quel sera votre auditoire, vous aurez une meilleure idée de ce dont vous aurez besoin pour faire passer votre sujet et comment l'utiliser.

  • 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 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

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 position géographique et votre culture, ou la culture actuelle et les manières de communiquer dans la communauté à laquelle vous appartenez ainsi que 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 bénévoles et joignez-vous à eux. 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 ?

Clareté et cohérence

Votre but est de rendre plus facile et plus intuitif l'accès, la lecture et la création de la documentation technique de MediaWiki/Wikimedia en promouvant la clareté et la cohérence. 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.

Example Audience Purpose[1] Potential Document Types Example
Newcomer interested in learning how to become a Toolforge user To learn Tutorial, FAQ, Getting Started guide Cloud VPS and Toolforge FAQ
Experienced technical contributor trying to work through a known problem To achieve a goal Walk-through, How-To guide My First Flask OAuth Tool
Individual trying to understand the history of ORES and how it evolved To understand Explanatory article, blog post, "overview" Artificial intelligence service “ORES” gives Wikipedians X-ray specs to see through bad edits
A person looking for a definition of SSH keys To inform Reference guide, glossary Glossary

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:

Voice and tone What this means Instead of this Try This
Friendly Technical documentation does not need to sound academic or dry. Write to your audience as if they are there in person. Before beginning, the user must create an account. Start by creating an account.
Professional Technical documentation can be friendly, but should remain professional. Use inclusive language. Don't make a bazillion changes. Try to make minimum changes.
Positive Avoid using negative sentence constructions. Explain things in terms of what to do. It is harder to mentally parse a complex negative sentence! N won't happen, if you don't XYZ. To make N happen, do XYZ.
Active Try to use active voice, except when diplomacy calls for passive voice. The extension must be registered. You must register the extension.
Non-gendered Adopt gender-inclusive language. Assume your audience comprises all gender identities. When he clicks Save When the user clicks Save
Inclusive Use alternatives to common words or phrases that may unintentionally reinforce inappropriate stereotypes. This UI is crazy. This UI could be improved.
Free of frustration Avoid terms like "easy" and "simple" which can be frustrating for less tech-savvy users. Simply create a user account. Create a user account.
Free of colloquialisms It can be confusing to use colloquialisms, jokes, puns, or turns of phrase that non-native English speakers or individuals from other regions might not easily understand. Creating a user account is a piece of cake. Creating a user account requires two steps.
This is not meant to be an exhaustive list or a strict set of rules.

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.

Dates

  • Always use the full, four-digit year.
  • Use absolute dates ("in May 2037") instead of relative dates ("next year in May").
  • Avoid adding dates that will require regular manual updates. Example: Write {{#time: Y }} instead of 2021 when referring to the current year, no matter what year it is currently.

Structuring pages

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 text

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.

Purpose Wiki-Markup Result Situation
Code <code>code</code> code Use for short strings of code, including wikitext markup.

Within <code>...</code>, use ''italics'' to indicate variables and sample names so users know what to replace.

Syntax highlight
<syntaxhighlight lang="css">
.citation {
    margin: 0;
}
</syntaxhighlight>

Text before <syntaxhighlight lang="css" inline>.foo {margin: 0;}</syntaxhighlight> text after.

.citation {
    margin: 0;
}

Text before .foo {margin: 0;} text after.

Use the <source lang="...">...</source> 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 <syntaxhighlight lang="foo">...</syntaxhighlight> block, so you have to fall back to YOURPASSWORD or The_page_title to indicate variables.

See Extension:SyntaxHighlight for more details.

Preformatted <pre>preformatted text

      with indent</pre>

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.

Note: Sometimes bold is overused for emphasis. You may consider using a template instead, e.g. {{Caution}}, {{Note}}, or {{Warning}}.

Quotations "quotation marks"

Text before

<blockquote>blockquote</blockquote>

Text after

"quotation marks" Text before

blockquote

Text after
Use quotation marks for brief pieces of content quoted from other sources.

Use blockquote for longer pieces of content.

Abbreviations JavaScript (JS)

<abbr title="JavaScript">JS</abbr>

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 VisualEditor/Portal/Keyboard shortcuts.

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.

Links

Type Purpose How to implement Example
Local Link to other MediaWiki pages
  • [[Foo]]
  • [[Foo|Bar]]
MediaWiki
Translated Target Link to other translated MediaWiki pages [[Special:MyLanguage/Foo|Foo]] How to contribute
Interwiki Link to page belonging to a different Wikimedia project
  • [[phab:T2001]] for tasks and project tags
  • [[mail:wikitech-l]] for mailing lists
  • [[w:en:foobar]] to English Wikipedia articles
  • [[wikitech:foobar]] for details about the WMF cluster
  • [[gerrit:604435]] for change requests in Gerrit
Documentation page on Wikipedia
External Link to external pages [https://www.example.org Example.org] Example

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:

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.

  • 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ées autour des titres de section peuvent perturber la modification des sections, et comme 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.

Informations supplémentaires

Voir aussi

Notes de bas de page