Live manual Debian Live

# Debian Live Manual

# Guide de style

861

# 17. Guide de style

862

17.1 Lignes directrices pour les auteurs

863

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.

864

Remarque: Les auteurs doivent lire d'abord Contribuer à ce document

865

17.1.1 Caractéristiques linguistiques

866

- Utilisez un anglais simple

867

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.

868

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.

869

- Variété de l'anglais

870

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.

871

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.

872

- Soyez équilibré

873

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.

874

- Soyez politiquement correct

875

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.

876

- Soyez concis

877

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.

878

- Minimiser le travail de traduction

879

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.

880

- Soyez cohérent

881

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.

882

- Soyez cohésive

883

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).

884

- Soyez descriptif

885

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.

886

- Dictionnaire

887

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.

888

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.

889

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é.

890

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.

891

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.

892

- Faux amis, expressions idiomatiques et autres expressions

893

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.

894

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!

895

- Évitez l'argot, les abréviations, les contractions...

896

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.

897

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.

898

17.1.2 Procédures

899

- Tester avant d'écrire

900

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.

901

- Exemples

902

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

903

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é.

904

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.

905

- Liens externes

906

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.

907

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

908

- Évitez les marques et les choses qui violent la licence sous laquelle le manuel est publié

909

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.

910

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.

911

- Ecrire un premier projet, réviser, modifier, améliorer, refaire si nécessaire

912

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

913

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

914

- Réviser la grammaire, la syntaxe et l'orthographe. Gardez à l'esprit que les noms propres des versions, tels que buster 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`

915

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

916

- Chapitres

917

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.

918

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.

919

- Balisage

920

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:

921

$ sisu --help markup

922

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

923

- Pour accent/texte en gras:

924

*{foo}* or !{foo}!

925

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

926

- Pour italique:

927

/{foo}/

928

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

929

- Pour monospace:

930

#{foo}#

931

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.

932

- Pour les blocs de code:

933

code{
$ foo
# bar
}code

934

il produit:

935

$ foo
# bar

936

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.

937

17.2 Lignes directrices pour les traducteurs

938

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

939

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.

940

Remarque: Les traducteurs doivent aussi lire Contribuer à ce document. En particulier, la section Traduction

941

17.2.1 Conseils de traduction

942

- Commentaires

943

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.

944

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.

945

- NDT, Note Du Traducteur

946

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 ".

947

- Phrases impersonnelles

948

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.

949

- Faux amis

950

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.

951

- Balisage

952

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.

953

- Blocs de code

954

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.

955

- Sauts de ligne

956

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.

957

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.

958

- Chaînes intraduisibles

959

Les traducteurs ne doivent jamais traduire:

960

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

961

- Les noms des logiciels

962

- Les commandes fournies à titre d'exemples

963

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

964

- Liens

965

- Les chemins