Style guide

Guia d'estil

Instruccions per als autors

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.

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

Característiques lingüístiques

●  Utilitzar un anglès planer

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.

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.

●  Varietat d'anglès

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.

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.

●  Ser equilibrat

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.

●  Ser políticament correcte

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

●  Ser concís

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.

●  Minimitzar la feina de traducció

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.

●  Ser coherent

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.

●  Cohesió

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

●  Ser descriptiu

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

●  Diccionari

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.

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.

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.

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.

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.

●  Falsos amics, modismes i altres expressions idiomàtiques

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.

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!

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

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

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.

Procediments

●  Provar abans d'escriure

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

●  Exemples

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.

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.

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.

●  Enllaços externs

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.

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

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

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.

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.

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

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

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

- Revisar la gramàtica, la sintaxi i l'ortografia. Tenir en compte que els noms propis de les versions, com ara ${testing} 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

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

●  Capítols

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

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.

●  Marcat

I per últim però no menys important, live-manual utilitza SiSU per processar els fitxers de text i produir múltiples formats. Es recomana fer una ullada al manual de SiSU per a familiaritzar-se amb el seu marcat, o bé escriure:

 $ sisu --help markup  

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

- Per a l'èmfasi/negreta:

*{foo}* o !{foo}!  

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

- Per a la cursiva:

/{foo}/  

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

- Per a monospace:

#{foo}#  

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

- Per a blocs de codi:

 code{

  $ foo
  # bar

 }code  

produeix:

 $ foo
 # bar  

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.

Directrius per als traductors

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

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.

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

Consells de traducció

●  Comentaris

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.

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.

●  NT, Nota del Traductor

É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”.

●  Frases impersonals

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.

●  Falsos amics

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.

●  Marcat

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.

●  Blocs de codi

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.

●  Salts de línia

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.

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.

●  Cadenes intraduïbles

Els traductors no han de traduir mai:

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

- Els noms dels programes

- Les ordres que es posen com a exemples

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

- Els enllaços

- Les rutes