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

:B~ Style guide

1~style-guide Guía de estilo

2~ Instrucciones para los autores

Esta sección se ocupa de algunas consideraciones generales a tener en cuenta
al escribir documentación técnica para live-manual. Se dividen en aspectos
lingüísticos y procedimientos recomendados.

*{Nota:}* Los autores deberían leer primero {contribuir a este documento}#how-to-contribute

3~ Aspectos lingüísticos

_* /{Utilizar un inglés llano}/

Tener en cuenta que un alto porcentaje de lectores no son hablantes nativos
de inglés. Así que, como regla general, se debe utilizar frases cortas y
significativas, seguidas de un punto y aparte.

Esto no significa que se tenga que utilizar un estilo simplista. Es una
sugerencia para tratar de evitar, en la medida de lo posible, las oraciones
subordinadas complejas que hacen que el texto sea difícil de entender para
los hablantes no nativos de inglés.

_* /{Variedad de inglés}/

Las variedades más extendidas del inglés son la británica y la americana,
así que es muy probable que la mayoría de los autores utilicen una u
otra. En un entorno de colaboración, la variedad ideal sería el "inglés
internacional", pero es muy difícil, por no decir imposible, decidir qué
variedad entre todas las existentes, es la mejor.

Esperamos que las diferentes variedades puedan mezclarse sin crear
malentendidos, pero en términos generales se debe tratar de ser coherente y
antes de decidir sobre el uso de las variantes británica o americana, o
cualquier otro tipo de inglés a su discreción, por favor, dar un vistazo a
cómo escriben otras personas y tratar de imitarlas.

_* /{Ser equilibrado}/

Hay que ser imparcial. Evitar incluir referencias a ideologías totalmente
ajenas a live-manual. La escritura técnica debe ser lo más neutral
posible. Está en la naturaleza misma de la escritura científica.

_* /{Ser políticamente correcto}/

Evitar el lenguaje sexista tanto como sea posible. Si se necesita hacer
referencia a la tercera persona del singular, utilizar preferiblemente
"they" en lugar de  "he" o "she" o inventos extraños como "s/he" o "s(he)".

_* /{Ser concisos}/

Ir directamente al grano y no dar vueltas a las cosas. Dar toda la
información necesaria, pero no dar más información de la necesaria, es
decir, no explicar detalles innecesarios. Los lectores son inteligentes. Se
presume algún conocimiento previo de su parte.

_* /{Minimizar la labor de traducción}/

Tener en cuenta que cualquier cosa que se escriba tendrá que ser traducido a
otros idiomas. Esto implica que un número de personas tendrán que hacer un
trabajo extra si se agrega información innecesaria o redundante.

_* /{Ser coherente}/

Como se ha sugerido anteriormente, es casi imposible estandarizar un
documento creado en colaboración en un todo perfectamente unificado. Sin
embargo, se aprecia todo esfuerzo por escribir de manera coherente con el
resto de los autores.

_* /{Cohesión}/

Utilizar conectores de discurso para conseguir un texto coherente y sin
ambigüedades. (Normalmente se llaman connectors).

_* /{Ser descriptivo}/

Es preferible describir el asunto en uno o varios párrafos que la mera
utilización de una serie de oraciones en un típico estilo de
"changelog". Hay que describirlo! Los lectores lo agradecerán.

_* /{Diccionario}/

Buscar el significado de las palabras en un diccionario o una enciclopedia
si no se sabe cómo expresar ciertos conceptos en inglés. Pero hay que tener
en cuenta que un diccionario puede ser el mejor amigo o puede convertirse en
el peor enemigo si no se utiliza correctamente.

El inglés tiene el mayor vocabulario que existe (con más de un millón de
palabras). Muchas de estas palabras son préstamos de otras lenguas. Al
buscar el significado de las palabras en un diccionario bilingüe la
tendencia de un hablante no nativo de inglés es elegir las que suenan más
similares en su lengua materna. A menudo, esto se convierte en un discurso
excesivamente formal que no suena muy natural en inglés.

Como regla general, si un concepto se puede expresar utilizando diferentes
sinónimos, es un buen consejo elegir la primera palabra propuesta por el
diccionario. En caso de duda, la elección de palabras de origen germánico
(Normalmente palabras monosílabas) es a menudo lo correcto. Tener en cuenta
que estas dos técnicas puede producir un discurso más bien informal, pero al
menos la elección de palabras será de amplio uso y aceptación general.

Se recomienda el uso de un diccionario de frases hechas. Son muy útiles
cuando se trata de saber qué palabras suelen aparecer juntas.

Una vez más, es una buena práctica aprender del trabajo de los otros. El uso
de un motor de búsqueda para comprobar cómo otros autores utilizan ciertas
expresiones puede ayudar mucho.

_* /{Falsos amigos, modismos y otras expresiones idiomáticas}/

Cuidado con los falsos amigos. No importa lo competente que se sea en un
idioma extranjero, se puede caer de vez en cuando en la trampa de los
llamados "falsos amigos", palabras que se parecen en dos idiomas pero cuyos
significados o usos pueden ser completamente diferentes.

Intentar evitar los modismos tanto como sea posible. Los "modismos" son
expresiones que tienen un significado completamente diferente de lo que sus
palabras parecen decir por separado. A veces, los modismos pueden resultar
difíciles de entender incluso para los hablantes nativos de inglés!

_* /{Evitar el argot, las abreviaturas, las contracciones...}/

A pesar de que se anime a utilizar un inglés sencillo, del día a día, la
escritura técnica pertenece al registro formal de la lengua.

Intentar evitar el argot, las abreviaturas inusuales que son difíciles de
entender y por encima de todo, las contracciones que tratan de imitar el
lenguaje hablado. Por no hablar de las expresiones familiares o típicas del
irc.

3~ Procedimientos

_* /{Probar antes de escribir}/

Es importante que los autores prueben sus ejemplos antes de añadirlos a
live-manual para asegurarse de que todo funciona como se describe. Hacer las
pruebas en un entorno chroot limpio o una máquina virtual puede ser un buen
punto de partida. Además, sería ideal si las pruebas fueran llevadas a cabo
en diferentes máquinas con un hardware diferente para detectar los posibles
problemas que puedan surgir.

_* /{Ejemplos}/

Cuando se pone un ejemplo hay que tratar de ser lo más específico
posible. Un ejemplo es, después de todo, tan sólo un ejemplo.

A menudo es mejor utilizar un ejemplo que sólo se aplica a un caso concreto
que el uso de abstracciones que puedan confundir a los lectores. En este
caso se puede dar una breve explicación de los efectos del ejemplo
propuesto.

Puede haber algunas excepciones cuando el ejemplo sugiera el uso de comandos
potencialmente peligrosos que, si se utilizan incorrectamente, pueden
provocar la pérdida de datos u otros efectos indeseables similares. En este
caso se debe proporcionar una explicación detallada acerca de los posibles
efectos secundarios.

_* /{Enlaces externos}/

Los enlaces a sitios externos sólo se deben utilizar cuando la información
en esos sitios es crucial para comprender un punto concreto. A pesar de eso,
tratar de utilizar enlaces a sitios externos lo menos posible. Los enlaces
de Internet pueden cambiar de vez en cuando, dando lugar a enlaces rotos y
dejando los argumentos en un estado incompleto.

Además, las personas que leen el manual sin conexión no tendrán la
oportunidad de seguir los enlaces.

_* /{Evitar las marcas y las cosas que violan la licencia bajo la que se
publica el manual}/

Tratar de evitar las marcas tanto como sea posible. Tener en cuenta que
otros proyectos derivados pueden hacer uso de la documentación que
escribimos. Así que estámos complicando las cosas para ellos si se añade
determinado material específico.

live-manual se publica bajo la GNU GPL. Esto tiene una serie de
implicaciones que se aplican a la distribución de los materiales (de
cualquier tipo, incluyendo gráficos o logos con derechos de autor) que se
publican en él.

_* /{Escribir un primer borrador, revisar, editar, mejorar, rehacer de nuevo
si es necesario}/

 - Lluvia de ideas!. Es necesario organizar las ideas primero en una
   secuencia lógica de eventos.

 - Una vez que, de alguna manera, se han organizado esas ideas en la mente,
   escribir un primer borrador.

 - Revisar la gramática, la sintaxis y la ortografía. Tener en cuenta que
   los nombres propios de las versiones, tales como ${testing} o sid, no se
   deben escribir en mayúscula cuando se refieren a los nombres en
   clave. Para comprobar la ortografía se puede ejecutar el target
   "spell". Es decir, #{make spell}#

 - Mejorar las frases y rehacer cualquier parte si es necesario.

_* /{Capítulos}/

Utilizar el sistema de numeración convencional de los capítulos y
subtítulos. Por ejemplo 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2,
2.1 ... y así sucesivamente. Ver marcado a continuación.

Si es necesario enumerar una serie de pasos o etapas en la descripción,
también se puede utilizar los números ordinales: primero, segundo, tercero
... o en primer lugar, entonces, después, por fin ... Alternativamente, se
pueden utilizar puntos.

_* /{Marcado}/

Y por último, pero no menos importante, live-manual utiliza
{SiSU}http://www.sisudoc.org/ para procesar los ficheros de texto y producir
múltiples formatos. Se recomienda echar un vistazo al {manual de
SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html para
familiarizarme con su marcado, o bien escribir:

code{

 $ sisu --help markup

}code

Estos son algunos ejemplos de marcado que pueden ser útiles:

 - Para el énfasis/negrita:

code{

*{foo}* o !{foo}!

}code

producen: *{foo}* o !{foo}!. Se usan para enfatizar ciertas palabras clave.

 - Para la cursiva:

code{

/{foo}/

}code

produce: /{foo}/.  Se usa, por ejemplo, para los nombres de paquetes Debian.

 - Para monospace:

code{

#{foo}#

}code

produce: #{foo}#. Se usa, por ejemplo, para los nombres de los comandos. Y
también para resaltar algunas palabras clave o cosas como las rutas.

 - Para los bloques de código:

code{

 code{

  $ foo
  # bar

 }code

}code

produce:

code{

 $ foo
 # bar

}code

Se utiliza #{code{}# para abrir y #{}code}# para cerrar los bloques. Es
importante recordar dejar un espacio al principio de cada línea de código.

2~guidelines-translators Directrices para los traductores

Esta sección se ocupa de algunas consideraciones generales a tener en cuenta
al traducir el contenido de live-manual.

Como recomendación general, los traductores deberían haber leído y entendido
las reglas de traducción que se aplican a sus lenguas específicas. Por lo
general, los grupos de traducción y las listas de correo proporcionan
información sobre cómo hacer traducciones que cumplan con los estándares de
calidad de Debian.

*{Nota:}* Los traductores también deberían leer {Cómo contribuir a este documento}#how-to-contribute. En particular, la sección {Traducción}#translation

3~ Consejos de traducción

_* /{Comentarios}/

El papel del traductor es transmitir lo más fielmente posible el significado
de las palabras, oraciones, párrafos y textos de como fueron escritos por
los autores originales a su idioma.

Así que ellos deben abstenerse de añadir comentarios personales o
informaciones adicionales por su cuenta. Si se desea agregar un comentario
para los traductores que trabajan en los mismos documentos, se pueden dejar
en el espacio reservado para ello. Es decir, el encabezado de las cadenas de
los ficheros *{po}* precedidos por el signo *{#}*. La mayoría de los
programas gráficos de traducción pueden manejar ese tipo de comentarios
automáticamente.

_* /{NT, Nota del Traductor}/

Es perfectamente aceptable, sin embargo, incluir una palabra o una expresión
entre paréntesis en el texto traducido si, y sólo si, hace que el
significado de una palabra o expresión difícil sea más clara para el
lector. Dentro de los paréntesis, el traductor debe poner de manifiesto que
la adición es suya utilizando la abreviatura "NT" o "Nota del traductor".

_* /{Frases impersonales}/

Los documentos escritos en Inglés utilizan muchísimo la forma impersonal
"you". En algunos otros idiomas que no comparten esta característica, esto
podría dar la falsa impresión de que los textos originales se dirigen
directamente el lector cuando en realidad no lo hacen. Los traductores deben
ser conscientes de este hecho y reflejarlo en su idioma con la mayor
precisión posible.

_* /{Falsos amigos}/

La trampa de los "falsos amigos" explicada anteriormente se aplica
especialmente a los traductores. Volver a comprobar el significado de los
falsos amigos sospechosos en caso de duda.

_* /{Marcado}/

Los traductores que trabajen inicialmente con los ficheros *{pot}* y
posteriormente con los ficheros *{po}* encontrarán muchas características de
marcado en las cadenas. Se puede traducir el texto, siempre que sea
traducible, pero es extremadamente importante que se utilice exactamente el
mismo marcado que la versión original en inglés.

_* /{Bloques de código}/

A pesar de que los bloques de código son generalmente intraducibles,
incluirlos en la traducción es la única manera de conseguir una traducción
completa al 100%. Y aunque eso signifique más trabajo al principio, ya que
puede ser necesaria la intervención de los traductores cuando hay cambios en
el código, es la mejor manera, a la larga, de identificar lo que se ha
traducido y lo que no al comprobar la integridad de los ficheros .po.

_* /{Saltos de línea}/

Los textos traducidos deben tener exactamente los mismos saltos de línea que
los textos originales. Tener cuidado de presionar la tecla "Enter" o
escribir *{\n}* si aparece en los ficheros originales. Estas nuevas líneas
aparecen a menudo, por ejemplo, en los bloques de código.

No hay que confundirse, esto no significa que el texto traducido tenga que
tener la misma longitud que la versión en inglés. Eso es prácticamente
imposible.

_* /{Cadenas intraducibles}/

Los traductores nunca deben traducir:

 - Los nombres en clave de las versiones (que debe ser escrito en
   minúsculas)

 - Los nombres de los programas

 - Los comandos que se ponen como ejemplos

 - Los metadatos (aparecen a menudo entre dos puntos *{:metadata:}*)

 - Los enlaces

 - Las rutas