Guide de style

Guide de style

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

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.

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 pour traiter les fichiers texte et pour produire plusieurs formats. Il est recommandé de consulter le manuel SiSU pour se familiariser avec son balisage, ou bien tapez:

 $ sisu --help markup  

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

- Pour accent/texte en gras:

*{foo}* or !{foo}!  

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

- Pour italique:

/{foo}/  

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

- Pour monospace:

#{foo}#  

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{

  $ foo
  # bar

 }code  

il produit:

 $ foo
 # bar  

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.

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. En particulier, la section Traduction

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