:B~ Guide de style

1~style-guide Guide de style

2~ Lignes directrices pour les auteurs

Cette section traite des considérations générales à prendre en compte lors
de la rédaction de la documentation technique pour live-manual. Elles sont
divisées en caractéristiques linguistiques et en procédures recommandées.

*{Remarque:}* Les auteurs doivent lire d'abord {Contribuer à ce document}#how-to-contribute

3~ Caractéristiques linguistiques

_* /{Utilisez un anglais simple}/

Gardez à l'esprit qu'un pourcentage élevé de vos lecteurs ne sont pas de
langue maternelle anglaise. Donc, en règle générale, essayez d'utiliser des
phrases significatives courtes, suivies d'un point.

Cela ne signifie pas que vous devez utiliser un style naïf et simpliste. Il
s'agit d'une suggestion pour essayer d'éviter, autant que possible, phrases
subordonnées complexes qui rendent le texte difficile à comprendre pour les
locuteurs non natifs de l'anglais.

_* /{Variété de l'anglais}/

Les variétés les plus répandues de l'anglais sont la britannique et
l'américain, donc il est très probable que la plupart des auteurs utilisent
l'un ou l'autre. Dans un environnement collaboratif, la variété idéale
serait «l'anglais international», mais il est très difficile, pour ne pas
dire impossible, de se prononcer sur quelle variété parmi toutes celles qui
existent déjà, est la meilleure à utiliser.

Nous croyons que les différentes variétés peuvent se mélanger sans créer
incompréhensions, mais en termes généraux, vous devriez essayer d'être
cohérent et avant de décider entre britannique, américain ou toute autre
variété anglaise à votre discrétion, s'il vous plaît jeter un oeil à la
façon dont d'autres gens écrivent et essayer de les imiter.

_* /{Soyez équilibré}/

Ne soyez pas partial. Évitez d'inclure des références à des idéologies
totalement étrangères à live-manual. L'écriture technique doit être aussi
neutre que possible. Il est dans la nature même de l'écriture scientifique.

_* /{Soyez politiquement correct}/

Essayez d'éviter un langage sexiste autant que possible. Si vous avez besoin
de faire référence à la troisième personne du singulier, de préférence
utilisez «they» plutôt que «he» ou «she» ou inventions maladroites telles
que «s/he», «s(he)», etc.

_* /{Soyez concis}/

Allez droit au but et ne pas errer sans but. Donner autant d'informations
que nécessaire, mais ne donnez pas plus d'informations que nécessaire,
c'est-à-dire, ne pas expliquer les détails inutiles. Vos lecteurs sont
intelligents. Présumez une certaine connaissance préalable de leur part.

_* /{Minimiser le travail de traduction}/

Gardez à l'esprit que ce que vous écrivez devra être traduit dans plusieurs
autres langues. Cela implique qu'un certain nombre de gens devront faire un
travail supplémentaire si vous ajoutez des informations inutiles ou
redondantes.

_* /{Soyez cohérent}/

Comme suggéré précédemment, il est presque impossible de normaliser un
document collaboratif dans un ensemble parfaitement unifié. Cependant, tous
les efforts de votre côté pour écrire d'une manière cohérente avec le reste
des auteurs seront appréciés.

_* /{Soyez cohésive}/

Utilisez autant de dispositifs de formation de texte que nécessaire pour
rendre votre texte cohésive et sans ambiguïtés. (Les dispositifs de
formation de texte sont des marqueurs linguistiques tels que les
connecteurs).

_* /{Soyez descriptif}/

Il est préférable de décrire le point en une ou plusieurs paragraphes que
simplement en utilisant un certain nombre de phrases dans un style typique
"changelog". Décrivez-le! Vos lecteurs apprécieront ça.

_* /{Dictionnaire}/

Cherchez le sens des mots dans un dictionnaire ou une encyclopédie si vous
ne savez pas comment exprimer certaines notions en anglais. Mais gardez à
l'esprit qu'un dictionnaire peut être votre meilleur ami ou peut se
transformer en votre pire ennemi si vous ne savez pas comment l'utiliser
correctement.

L'anglais possède le plus grand vocabulaire qui existe (avec plus d'un
million de mots). Beaucoup de ces mots sont des emprunts d'autres
langues. Lorsque l'on regarde le sens des mots dans un dictionnaire
bilingue, la tendance d'un locuteur non natif de l'anglais est de choisir
celui qui sonne plus similaire dans leur langue maternelle. Cela se
transforme souvent en un discours excessivement formelle qui ne semble pas
tout à fait naturel en anglais.

En règle générale, si un concept peut être exprimé en utilisant différents
synonymes, c'est un bon conseil choisir le premier mot proposé par le
dictionnaire. En cas de doute, le choix des mots d'origine germanique
(Habituellement mots monosyllabiques) est souvent la bonne chose à faire. Il
faut savoir que ces deux techniques peuvent produire un discours plutôt
informel, mais au moins votre choix des mots sera d'utilisation grand et
généralement accepté.

L'utilisation d'un dictionnaire de collocations est recommandé. Ils sont
extrêmement utiles quand il s'agit de savoir quels mots surviennent
généralement ensemble.

Encore une fois, c'est une bonne pratique apprendre à partir du travail des
autres. Grâce à un moteur de recherche pour vérifier comment les autres
auteurs utilisent certaines expressions peut aider beaucoup.

_* /{Faux amis, expressions idiomatiques et autres expressions}/

Attention aux faux amis. Peu importe comment vous êtes compétent dans une
langue étrangère, vous ne pouvez pas vous empêcher de tomber de temps en
temps dans le piège de ce qu'on appelle les «faux amis», des mots qui se
ressemblent dans les deux langues, mais dont les significations ou les
utilisations pourrait être complètement différent.

Essayez d'éviter les expressions idiomatiques autant que possible. Les
expressions idiomatiques sont des expressions qui peuvent transmettre un
sens complètement différent de ce que leurs mots individuels semblent
signifier. Parfois, les expressions idiomatiques peuvent être difficiles à
comprendre, même pour les locuteurs natifs de l'anglais!

_* /{Évitez l'argot, les abréviations, les contractions...}/

Même si vous êtes encouragés à utiliser un langage simple, l'anglais de tous
les jours, la rédaction technique appartient au registre formel de la
langue.

Essayez d'éviter l'argot, abréviations inhabituels qui sont difficiles à
comprendre et surtout les contractions qui tentent d'imiter le langage
parlé. Sans oublier typique expressions d'irc et favorables à la famille.

3~ Procédures

_* /{Tester avant d'écrire}/

Il est important que les auteurs testent leurs exemples avant de les ajouter
à live-manual pour s'assurer que tout fonctionne comme décrit. Tester sur
​​un chroot propre ou une machine virtuelle peut être un bon point de
départ. Par ailleurs, il serait idéal si les tests ont ensuite été effectués
sur des machines différentes avec un matériel différent pour repérer
d'éventuels problèmes qui pourraient survenir.

_* /{Exemples}/

En fournissant un exemple essayer d'être aussi précis que possible. Un
exemple est, après tout, juste un exemple.

Il est souvent préférable d'utiliser une ligne qui ne s'applique qu'à un cas
particulier que l'utilisation d'abstractions qui peuvent confondre vos
lecteurs. Dans ce cas, vous pouvez fournir une brève explication des effets
de l'exemple proposé.

Il peut y avoir des exceptions lorsque l'exemple suggère d'utiliser
certaines commandes potentiellement dangereuses qui, si elles sont mal
utilisées, peuvent causer des pertes de données ou d'autres effets
indésirables similaires. Dans ce cas, vous devez fournir une explication
approfondie des effets secondaires possibles.

_* /{Liens externes}/

Les liens externes ne doivent être utilisés lorsque l'information sur ces
sites est cruciale quand il s'agit de comprendre un point particulier. Même
si, essayez d'utiliser des liens externes aussi peu que possible. Les liens
internet sont susceptibles de changer de temps en temps résultant en des
liens brisés et en laissant vos arguments dans un état incomplet.

D'ailleurs, les gens qui lisent le manuel hors ligne n'auront pas la chance
de suivre ces liens.

_* /{Évitez les marques et les choses qui violent la licence sous laquelle
le manuel est publié}/

Essayez d'éviter les marques autant que possible. Gardez à l'esprit que
d'autres projets peuvent utiliser la documentation que vous écrivez. Donc,
vous compliquez les choses pour eux si vous ajoutez certaines matières
spécifiques.

live-manual est sous la licence GNU GPL. Cela a un certain nombre de
conséquences qui s'appliquent à la distribution de la matière (de toute
nature, y compris les graphiques ou logos protégées) qui est publiée avec le
manuel.

_* /{Ecrire un premier projet, réviser, modifier, améliorer, refaire si
nécessaire}/

 - Remue-méninges!. Vous devez organiser vos idées d'abord dans une séquence
   logique des événements.

 - Une fois que vous avez en quelque sorte organisé ces idées dans votre
   esprit écrire un premier projet.

 - Réviser la grammaire, la syntaxe et l'orthographe. Gardez à l'esprit que
   les noms propres des versions, tels que ${testing} ou sid, ne doivent pas
   être capitalisés lorsqu'ils sont utilisés comme noms de code. Pour
   vérifier l'orthographe, on peut exécuter la cible "spell". C'est à dire,
   #{make spell}#

 - Améliorer vos phrases et refaire n'importe quelle partie si nécessaire.

_* /{Chapitres}/

Utilisez le système de numérotation classique des chapitres et
sous-titres. Par exemple 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2,
2.1 ... et cetera. Voir marqueurs ci-dessous.

Si vous avez d'énumérer une série d'étapes ou phases dans votre description,
vous pouvez également utiliser des nombres ordinaux: premier, deuxième,
troisième ... ou d'abord, puis, après cela, enfin ... Sinon, vous pouvez
utiliser les éléments à puces.

_* /{Balisage}/

Et finalement, live-manual utilise {SiSU}http://www.sisudoc.org/ pour
traiter les fichiers texte et pour produire plusieurs formats. Il est
recommandé de consulter le {manuel
SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html pour se
familiariser avec son balisage, ou bien tapez:

code{

 $ sisu --help markup

}code

Voici quelques exemples de balisage qui peuvent éventuellement vous aider:

 - Pour accent/texte en gras:

code{

*{foo}* or !{foo}!

}code

il produit: *{foo}* or !{foo}!. Utiliser pour mettre l'accent sur certains
mots-clés.

 - Pour italique:

code{

/{foo}/

}code

il produit: /{foo}/. Utiliser par exemple, pour les noms des paquets Debian.

 - Pour monospace:

code{

#{foo}#

}code

il produit: #{foo}#. Utiliser par exemple, pour les noms des commandes. Et
aussi pour souligner certains mots clés ou des choses comme les chemins.

 - Pour les blocs de code:

code{

 code{

  $ foo
  # bar

 }code

}code

il produit:

code{

 $ foo
 # bar

}code

Utilisez #{code{}# pour ouvrir et #{}code}# pour fermer les balises. Il est
important de se rappeler de laisser un espace au début de chaque ligne de
code.

2~guidelines-translators Lignes directrices pour les traducteurs

Cette section traite des considérations générales à prendre en compte lors
de la traduction du contenu du live-manual.

Comme recommandation générale, les traducteurs doivent avoir lu et compris
les règles de traduction qui s'appliquent à leurs langues
spécifiques. Habituellement, les groupes de traduction et listes de
diffusion fournissent des informations sur la façon de produire un travail
de traduction qui respecte les normes de qualité de Debian.

*{Remarque:}* Les traducteurs doivent aussi lire {Contribuer à ce document}#how-to-contribute. En particulier, la section {Traduction}#translation

3~ Conseils de traduction

_* /{Commentaires}/

Le rôle du traducteur est de transmettre le plus fidèlement possible le sens
des mots, des phrases, des paragraphes et des textes comme écrit par les
auteurs originaux dans leur langue cible.

Donc, ils devraient s'abstenir d'ajouter des commentaires personnels ou des
morceaux d'informations supplémentaires de leur propre chef. S'ils veulent
ajouter un commentaire pour d'autres traducteurs travaillant sur les mêmes
documents, ils peuvent le laisser dans l'espace réservé pour cela. Autrement
dit, l'en-tête des chaînes dans les fichiers *{po}* précédés d'un signe
*{#}*. Nombreuses logiciels de traduction graphiques peuvent gérer
automatiquement ces types de commentaires.

_* /{NDT, Note Du Traducteur}/

Il est parfaitement acceptable cependant, inclure un mot ou une expression
entre parenthèses dans le texte traduit si, et seulement si, cela fait le
sens d'un mot ou d'une expression difficile plus clair pour le lecteur. A
l'intérieur des parenthèses, le traducteur doit mettre en évidence que
l'addition a été leur en utilisant l'abréviation "NDT" ou "Note Du
Traducteur ". 

_* /{Phrases impersonnelles}/

Les documents écrits en anglais font une utilisation intensive de la forme
impersonnelle "you". Dans d'autres langues qui ne partagent pas cette
caractéristique, ce pourrait donner la fausse impression que les textes
originaux traitent directement le lecteur quand en réalité ils ne le font
pas. Les traducteurs doivent être conscients de ce fait et traduir dans leur
langue le plus fidèlement que possible.

_* /{Faux amis}/

Le piège des "faux amis" expliqué avant s'applique surtout aux
traducteurs. Vérifiez le sens des faux amis suspects en cas de doute.

_* /{Balisage}/

Les traducteurs qui travaillent d'abord avec les fichiers *{pot}* et plus
tard avec les fichiers *{po}* trouveront de nombreuses caractéristiques de
balisage dans les chaînes. Ils peuvent traduire le texte de toute façon,
tant qu'il est traduisible, mais il est extrêmement important qu'ils
utilisent exactement le même balisage que la version originale anglaise.

_* /{Blocs de code}/

Même si les blocs de code sont généralement intraduisibles, les inclure dans
la traduction est la seule façon d'obtenir une traduction complète 100%. Et
même si cela signifie plus de travail au début car ça peut exiger
l'intervention des traducteurs si le code change, il est le meilleur moyen,
à long terme, d'identifier ce qui a déjà été traduit et ce qui n'a pas, lors
de la vérification de l'intégrité des fichiers .po.

_* /{Sauts de ligne}/

Les textes traduits doivent avoir les mêmes sauts de lignes exactes que les
textes originaux. Veillez appuyer sur "Entrée" ou tapez *{\n}* si elles
apparaissent dans les fichiers originaux. Ces nouvelles lignes apparaissent
souvent, par exemple, dans les blocs de code.

Ne vous méprenez pas, cela ne signifie pas que le texte traduit doit avoir
la même longueur que la version anglaise. C'est presque impossible.

_* /{Chaînes intraduisibles}/

Les traducteurs ne doivent jamais traduire:

 - Les noms de code des versions (qui doivent être écrits en minuscules)

 - Les noms des logiciels

 - Les commandes fournies à titre d'exemples

 - Métadonnées (souvent entre deux points *{:metadata:}*)

 - Liens

 - Les chemins
