Live manual Debian Live

# Debian Live Manual

# Style guide

861

# 17. Guia d'estil

862

17.1 Instruccions per als autors

863

Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte al escriure documentació tècnica per a live-manual. Es divideixen en aspectes lingüístics i procediments recomanats.

864

Nota: Els autors han de llegir primer Contribuir a aquest document

865

17.1.1 Característiques lingüístiques

866

- Utilitzar un anglès planer

867

Tenir en compte que un alt percentatge dels lectors no són parlants nadius d'anglès. Així que, com a regla general, intentar utilitzar frases curtes i significatives, seguides d'un punt i apart.

868

Això no vol dir que s'hagi d'utilitzar un estil simplista i ingenu. És un suggeriment per intentar evitar, en la mesura del possible, les oracions subordinades complexes que fan que el text sigui difícil d'entendre per als parlants no nadius d'anglès.

869

- Varietat d'anglès

870

Les varietats d'anglès més esteses són el britànic i l'americà, així que és molt probable que la majoria dels autors acabin utilitzant l'una o l'altra. En un entorn de col·laboració, la varietat ideal seria "l'anglès internacional", però és molt difícil, per no dir impossible, decidir quina varietat d'entre totes les existents, és la millor.

871

Esperem que les diferents varietats es puguin barrejar sense crear malentesos, però en termes generals s'ha d'intentar ser coherent i abans de decidir sobre l'ús de l'anglès britànic, l'anglès americà o qualsevol altra varietat, fer una ullada a com escriuen altres persones i tractar d'imitar l'estil.

872

- Ser equilibrat

873

S'ha de ser imparcial. Evitar incloure referències a ideologies totalment alienes a live-manual. L'escriptura tècnica ha de ser el més neutral possible. Està en la naturalesa mateixa de l'escriptura científica.

874

- Ser políticament correcte

875

Evitar el llenguatge sexista tant com sigui possible. Si es necessita fer referència a la tercera persona del singular utilitzar preferiblement "they" en lloc de "he" or "she" o invents estranys com per exemple "s/he" o "s(he)".

876

- Ser concís

877

Anar directament al gra i no fent voltes. Donar tota la informació necessària, però no afegir més informació de la necessària, és a dir, no explicar detalls innecessaris. Els lectors són intel·ligents. Es presumeix algun coneixement previ per la seva part.

878

- Minimitzar la feina de traducció

879

Tenir en compte que qualsevol cosa que s'escrigui haurà de ser traduida a diverses llengües. Això implica que un nombre de persones hauran de fer un treball extra si s'agrega informació innecessària o redundant.

880

- Ser coherent

881

Com s'ha suggerit abans, és gairebé impossible estandarditzar un document escrit en col·laboració en un tot perfectament unificat. No obstant això, s'aprecia tot esforç per escriure d'una manera coherent amb la resta dels autors.

882

- Cohesió

883

Utilitzar connectors del discurs perquè el text sigui coherent i sense ambigüitats. (Normalment s'anomenen connectors).

884

- Ser descriptiu

885

És preferible descriure l'assumpte en un o diversos paràgrafs en lloc d'utilitzar una sèrie de oracions en un típic estil de "changelog". Cal descriure-ho! Els Lectors ho agrairan.

886

- Diccionari

887

Buscar el significat de les paraules en un diccionari o una enciclopèdia si no es sap com expressar certs conceptes en anglès. Però cal tenir en compte que un diccionari pot ser el millor amic o pot convertir-se en el pitjor enemic si no es sap com utilitzar-lo correctament.

888

L'anglès té el vocabulari més gran que existeix (amb més d'un milió de paraules). Moltes d'aquestes paraules són préstecs d'altres llengües. Al buscar el significat de les paraules en un diccionari bilingüe la tendència d'un parlant no nadiu d'anglès és triar la que sona més semblant en la seva llengua materna. Sovint, això es converteix en un discurs excessivament formal que no sona ben natural en anglès.

889

Com a regla general, si un concepte es pot expressar utilitzant diferents sinònims, és un bon consell triar la primera paraula proposada pel diccionari. En cas de dubte, és sovint correcte elegir les paraules d'origen germànic (Normalment paraules monosíl·labes). Tenir en compte que aquestes dues tècniques poden produir un discurs més aviat informal, però almenys la elecció de paraules serà d'ampli ús i acceptació general.

890

L'ús d'un diccionari de frases fetes es recomanable. Són molt útils quan es tracta de saber quines paraules solen aparèixer juntes.

891

Com s'ha dit abans, és una bona pràctica aprendre del treball dels altres. L'ús d'un motor de recerca per comprovar com altres autors utilitzen certes expressions pot ajudar molt.

892

- Falsos amics, modismes i altres expressions idiomàtiques

893

Compte amb els falsos amics. No importa com de competent un és en un idioma estranger, de tant en tant es pot caure en el parany dels anomenats "falsos amics", paraules que s'assemblen en dos idiomes però els significats o usos poden ser completament diferents.

894

Intentar evitar els modismes tant com sigui possible. Els "modismes " són expressions que tenen un significat completament diferent del que les seves paraules per separat semblen voler dir. De vegades, els modismes poden ser difícils d'entendre fins i tot per als parlants nadius d'anglès!

895

- Evitar l'argot, les abreviatures, les contraccions...

896

Tot i que s'anima a utilitzar un anglès senzill i planer, l'escriptura tècnica pertany al registre formal de la llengua.

897

Intentar evitar l'argot, les abreviatures inusuals que són difícils d'entendre i per sobre de tot, les contraccions que tracten d'imitar el llenguatge parlat. Per no parlar d'expressions familiars o típiques de l'irc.

898

17.1.2 Procediments

899

- Provar abans d'escriure

900

És important que els autors provin els seus exemples abans d'afegir-los a live-manual per assegurar-se que tot funciona com es descriu. Fer les proves en un entorn chroot net o en una màquina virtual pot ser un bon punt de partida. A més, seria ideal si les proves fossin dutes a terme en diferents ordinadors amb un maquinari diferent per detectar els possibles problemes que puguin sorgir.

901

- Exemples

902

Quan es posa un exemple mirar de ser el més específic possible. Un exemple és, després de tot, només un exemple.

903

Sovint és millor utilitzar una línia que només s'aplica a un cas concret que l'ús d'abstraccions que poden confondre als lectors. En aquest cas es pot donar una breu explicació dels efectes de l'exemple proposat.

904

Hi pot haver algunes excepcions quan l'exemple suggereixi l'ús d'algunes ordres potencialment perilloses que, si s'utilitzen incorrectament, poden provocar la pèrdua de dades o altres efectes indesitjables similars. En aquest cas, s'haurà de proporcionar una explicació detallada sobre els possibles efectes secundaris.

905

- Enllaços externs

906

Els enllaços a llocs externs només s'han d'utilitzar quan la informació en aquests llocs és crucial per a comprendre un punt especial. Tot i això, intentar utilitzar els enllaços a llocs externs el menys possible. Els enllaços d'internet poden canviar de tant en tant, donant lloc a enllaços trencats i deixant els arguments en un estat incomplet.

907

A més, la gent que llegeix el manual sense connexió no podrà seguir els enllaços.

908

- Evitar les marques i les coses que violen la llicència sota la qual es publica el manual

909

Intentar evitar les marques tant com sigui possible. Tenir en compte que altres projectes derivats poden fer ús de la documentació que escrivim. Així que estem complicant les coses per a ells si s'afegix determinat material específic.

910

live-manual es publica sota la llicència GNU GPL. Això té una sèrie d'implicacions que s'apliquen a la distribució dels materials (de qualsevol tipus, incloent-hi gràfics o logotips amb drets d'autor) que es publica amb ell.

911

- Escriure un primer esborrany, revisar, editar, millorar, fer de nou si és necessari

912

- Pluja d'idees!. Es necessari organitzar les idees primer en una seqüència lògica d'esdeveniments.

913

- Quan d'alguna manera ja s'han organitzat aquestes idees en la ment, escriure un primer esborrany.

914

- Revisar la gramàtica, la sintaxi i l'ortografia. Tenir en compte que els noms propis de les versions, com ara buster o sid, no s'han d'escriure en majúscula quan es refereixen als noms en clau. Per tal de comprovar l'ortografia es pot executar el target "spell". És a dir, `make spell`

915

- Millorar les frases i refer qualsevol part si és necessari.

916

- Capítols

917

Utilitzar el sistema de numeració convencional dels capítols i subtítols. Per exemple 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... i així successivament. Veure marcat a continuació.

918

Si s'ha d'enumerar una sèrie de passos o etapes en la descripció, també es poden utilitzar els nombres ordinals: primer, segon, tercer ... o en primer lloc, llavors, després, per fi ... Alternativament, es poden utilitzar punts.

919

- Marcat

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

Aquests són alguns exemples de marcat que poden ser útils:

923

- Per a l'èmfasi/negreta:

924

*{foo}* o !{foo}!

925

produeixen: foo o foo. S'usen per emfatitzar certes paraules clau.

926

- Per a la cursiva:

927

/{foo}/

928

produeix: foo. S'usa, per exemple, per als noms dels paquets Debian.

929

- Per a monospace:

930

#{foo}#

931

produeix: `foo`. S'usa per exemple, per als noms de les ordres. I també per ressaltar algunes paraules clau o coses com les rutes.

932

- Per a blocs de codi:

933

code{
$ foo
# bar
}code

934

produeix:

935

$ foo
# bar

936

S'utilitza `code{` per a obrir i `}code` per a tancar els blocs. És important recordar deixar un espai al principi de cada línia de codi.

937

17.2 Directrius per als traductors

938

Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte a l'hora de traduir el contingut de live-manual.

939

Com a recomanació general, els traductors haurien d'haver llegit i entès les regles de traducció que s'apliquen als seus llenguatges específics. En general, els grups de traductors i les llistes de correu proporcionen informació sobre com produir traduccions que compleixin amb els estàndards de qualitat de Debian.

940

Nota: Els traductors també han de llegir Contribuir a aquest document. En particular, la secció Traducció

941

17.2.1 Consells de traducció

942

- Comentaris

943

El paper del traductor és transmetre el més fidelment possible el significat de les paraules, oracions, paràgrafs i textos de com van ser escrits pels autors originals al seu idioma.

944

Per tant, aquests, s'han d'abstenir d'afegir comentaris personals o informacions addicionals pel seu compte. Si es vol afegir un comentari per als traductors que treballen en els mateixos documents, es poden deixar a l'espai reservat per a això. És a dir, la capçalera de les cadenes dels fitxers po precedits pel signe #. La majoria dels programes gràfics de traducció poden manejar aquest tipus de comentaris automàticament.

945

- NT, Nota del Traductor

946

És perfectament acceptable però, incloure una paraula o una expressió entre parèntesi en el text traduït si, i només si, aixó fa que el significat d'una paraula o expressió difícil sigui més clara per al lector. Dins dels parèntesis, el traductor ha de posar de manifest que l'addició és seva utilitzant l'abreviatura "NT" o "Nota del traductor".

947

- Frases impersonals

948

Els documents escrits en anglès fan un gran ús de la forma impersonal "you". En alguns altres idiomes que no comparteixen aquesta característica, això pot donar la falsa impressió que els textos originals s'adresen directament el lector quan en realitat n'ho fan. Els traductors han de ser conscients d'aquest fet i ho han de reflectir en el seu idioma amb la major precisió possible.

949

- Falsos amics

950

El perill dels "falsos amics" explicat anteriorment s'aplica especialment als traductors. Tornar a comprovar el significat dels falsos amics sospitosos en cas de dubte.

951

- Marcat

952

Els traductors que treballin inicialment amb els fitxers pot i posteriorment amb els fitxers po trobaràn moltes característiques de marcat en les cadenes. Es pot traduir el text, sempre que sigui traduïble, però és extremadament important que s'utilitzi exactament el mateix marcat que a la versió original en anglès.

953

- Blocs de codi

954

Tot i que els blocs de codi són generalment intraduïbles, incloure'ls en la traducció és l'única manera de conseguir una traducció completa al 100%. I encara que això signifiqui més feina al principi, ja que pot requerir la intervenció dels traductors s'hi ha canvis en el codi, és la millor manera, a la llarga, per identificar el que s'ha traduït i el que no al comprovar la integritat dels fitxers .po.

955

- Salts de línia

956

Els texts traduïts han de tenir exactament els mateixos salts de línia que els texts originals. Aneu amb compte de pressionar la tecla "Enter" o escriure \n si apareix als fitxers originals. Aquests salts de línies apareixen sovint, per exemple, en els blocs de codi.

957

No confondre's, això no vol dir que el text traduït hagi de tenir la mateixa longitud que la versió en anglès. Aixó és gairebé impossible.

958

- Cadenes intraduïbles

959

Els traductors no han de traduir mai:

960

- Els noms en clau de les versions (que han de ser escrits en minúscules)

961

- Els noms dels programes

962

- Les ordres que es posen com a exemples

963

- Les metadades (apareixen sovint entre dos punts :metadata:)

964

- Els enllaços

965

- Les rutes