Style guide

Guía de estilo

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

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.

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 para procesar los ficheros de texto y producir múltiples formatos. Se recomienda echar un vistazo al manual de SiSU para familiarizarme con su marcado, o bien escribir:

 $ sisu --help markup  

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

- Para el énfasis/negrita:

*{foo}* o !{foo}!  

producen: foo o foo. Se usan para enfatizar ciertas palabras clave.

- Para la cursiva:

/{foo}/  

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

- Para monospace:

#{foo}#  

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{

  $ foo
  # bar

 }code  

produce:

 $ foo
 # bar  

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.

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. En particular, la sección Traducción

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