path: root/markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi

:B~ Style guide

1~style-guide Guia d'estil

2~ 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}#how-to-contribute

3~ 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.

3~ 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}http://www.sisudoc.org/ per processar els fitxers de text i produir
múltiples formats. Es recomana fer una ullada al {manual de
SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html per a
familiaritzar-se amb el seu marcat, o bé escriure:

code{

 $ sisu --help markup

}code

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

 - Per a l'èmfasi/negreta:

code{

*{foo}* o !{foo}!

}code

produeixen: *{foo}* o !{foo}!. S'usen per emfatitzar certes paraules clau.

 - Per a la cursiva:

code{

/{foo}/

}code

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

 - Per a monospace:

code{

#{foo}#

}code

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{

 code{

  $ foo
  # bar

 }code

}code

produeix:

code{

 $ foo
 # bar

}code

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.

2~guidelines-translators 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}#how-to-contribute. En particular, la secció {Traducció}#translation

3~ 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