1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
---
title: Guide stylistique
slug: MDN/Guidelines/Writing_style_guide
tags:
- Documentation
- Guide
- Guidelines
- MDN
- MDN Meta
- MDN Web Docs
- MDN style guide
- Style guide
- Writing style guide
translation_of: MDN/Guidelines/Writing_style_guide
---
<div>{{MDNSidebar}}</div>
<p>Afin de présenter la documentation de façon organisée, cohérente et facile à lire, le guide stylistique de MDN décrit la façon dont le texte doit être organisé, orthographié, mis en forme, etc. Il s'agit ici de règles générales plutôt que de consignes strictes. Le contenu importe plus que la forme et il n'y a pas d'obligation à apprendre ce guide avant de contribuer. Toutefois, ne soyez pas surpris⋅e si une contributrice ou un contributeur édite une de vos éditions pour respecter ce guide.</p>
<p>La suite de ce guide vise avant tout la documentation francophone. Elle reprend des parties du <a href="/en-US/docs/MDN/Guidelines/Writing_style_guide">guide stylistique anglophone</a> lorsque c'est pertinent. Vous pouvez également consulter <a href="https://github.com/mozfr/besogne/wiki/Guide-stylistique-pour-la-traduction">le guide stylistique de la communauté francophone</a>. Si vous souhaitez contribuer au contenu en anglais, rapportez vous au <a href="/en-US/docs/MDN/Guidelines/Writing_style_guide">guide stylistique anglophone</a>.</p>
<h2 id="Basics">Règles de base</h2>
<p>Voici quelques règles simples qui permettent de conserver une cohérence dans la documentation.</p>
<h3 id="Page_titles">Titres des pages</h3>
<p>Les titres des pages sont utilisés dans les résultats des recherches et affichés dans les fils d'Ariane en haut de la page. Le titre de la page pourra être différent de la partie d'URL du document. En français, il devra l'être (car le fragment d'URL sera anglophone).</p>
<h4 id="Title_and_heading_capitalization">Titres et capitales</h4>
<p>Seul le premier terme d'un titre (de page ou de section) devra être en capitale :</p>
<ul>
<li><strong>Correct</strong> : « Une nouvelle méthode pour créer des objets JavaScript »</li>
<li><strong>Incorrect</strong>: « Une Nouvelle Méthode pour Créer des Objets JavaScript »</li>
</ul>
<p>Si vous voyez certains titres qui enfreignent cette règle, n'hésitez pas à contribuer pour les corriger.</p>
<h4 id="Choosing_titles_and_slugs">Choix des titres</h4>
<p>Contrairement au fragment d'URL de la page (court et fixé par la version anglophone), on pourra choisir un titre descriptif suffisamment long.</p>
<h4 id="Creating_new_subtrees">Création de nouvelles pages</h4>
<p>Le contenu francophone « suit » le contenu anglophone. Toute nouvelle page de MDN devra d'abord être créée avec sa version anglaise avant d'être traduite.</p>
<h3 id="Code_sample_style_and_formatting">Style et mise en forme des exemples de code</h3>
<p>On pourra traduire les noms de certaines variables pour les franciser (par exemple <code>toto</code> à la place de <code>foo</code>) et on traduira les commentaires</p>
<h4 id="Tabs_and_line_breaks">Sauts de ligne</h4>
<p>Pour un fragment de code, on évitera d'avoir une ligne trop longue qui nécessite de faire défiler le contenu horizontal. On privilégiera les ruptures de lignes naturelles :</p>
<pre class="brush: js">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
|| class.YET_ANOTHER_CONDITION ) {
/* quelque chose */
}
var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
.createInstance(Components.interfaces.nsIToolkitProfileService);
</pre>
<h3 id="Latin_abbreviations">Abréviations</h3>
<div class="note">
<p><strong>Note :</strong> les abréviations sont à utiliser à bon escient et il faudra bien connaître leur sens (notamment pour les abrévations latines) afin de les utiliser correctement. Il faut être conscient que leur usage peut être source de confusion pour les lectrices et lecteurs qui pourraient ne pas y être habitués.</p>
</div>
<h4 id="In_notes_and_parentheses">Dans les notes et parenthèses</h4>
<p>Les abréviations communes (etc., i.e.) pourront être utilisées dans les notes et entre parenthèses. Attention, on utilisera ex. plutôt que e.g. qui est usité en anglais (ou que p. ex. qui est moins usité).</p>
<h4 id="In_running_text">Dans le texte</h4>
<ul>
<li>Dans le texte principal (en dehors des notes ou des parenthèses), on privilégiera les formes développées plutôt que les abréviations.
<ul>
<li><strong>Correct</strong> : les navigateurs web tels que Firefox peuvent être utilisés…</li>
<li><strong>Incorrect</strong> : les navigateurs, ex. Firefox, peuvent être utilisés…</li>
</ul>
</li>
</ul>
<h3 id="Acronyms_and_abbreviations">Acronymes et abréviations</h3>
<h4 id="Capitalization_and_periods">Capitalisation et usage des points</h4>
<p>Les acronymes seront écrits en capitales et sans point.</p>
<ul>
<li><strong>Correct</strong> : API</li>
<li><strong>Incorrect</strong> : A.P.I. ; Api</li>
</ul>
<h4 id="Expansion">Explication</h4>
<p>Lors de la première mention d'un terme abrégé sur une page, on expliquera l'acronyme et/ou on liera vers le <a href="/fr/docs/Glossary">glossaire</a>.</p>
<h4 id="Plurals_of_acronyms_and_abbreviations">Pluriels des acronymes</h4>
<p>Contrairement aux pratiques anglophones, on n'apportera pas de s pour les formes plurielles des acronymes.</p>
<ul>
<li><strong>Correct</strong> : les API du Web</li>
<li><strong>Incorrect</strong> : les APIs du Web</li>
</ul>
<h3 id="Punctuation">Ponctuation</h3>
<h4 id="Apostrophes_and_quotation_marks">Apostrophes et guillemets</h4>
<p><strong>On n'utilisera pas d'apostrophe courbe sur MDN.</strong> L'usage des guillemets français est autorisé (mais pas obligatoire) et ceux-ci ne doivent pas servir dans du code pour délimiter des chaînes de caractères où il faudra utiliser les doubles quotes.</p>
<h3 id="Spelling">Orthographe</h3>
<p>On recommandera l'utilisation de <a href="https://addons.mozilla.org/fr/firefox/addon/grammalecte-fr/">Grammalecte</a> pour vérifier l'orthographe d'un document.</p>
<h3 id="Terminology">Terminologie</h3>
<p>En cas de doute sur la formulation en français d'un terme ou d'une expression anglaise, on privilégiera l'usage, <a href="transvision.mozfr.org/">Transvision</a>, <a href="https://fr.wikipedia.org">Wikipédia</a>.</p>
|
