|
|
|
|
|
|
|
|
|
|
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
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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!
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.
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.
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.
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.
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.
- 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 trixie 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.
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.
And last but not least, live-manual uses SiSU to process the text files and produce a multiple format output. It is recommended to take a look at SiSU's manual to get familiar with its markup, or else type:
$ 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.
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
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.
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 ".
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.
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.
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.
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.
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.
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
|
|
|