aboutsummaryrefslogtreecommitdiffhomepage
path: root/markup/pod/live-manual/media/text/es/appendix_style-guide.ssi
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2021-11-27 21:54:49 -0500
committerRalph Amissah <ralph.amissah@gmail.com>2021-11-27 21:54:49 -0500
commit78b1b83be0cf04b4cba707751b7ad4d97787fe37 (patch)
tree0260daae62c3c0c055b7ec73b274fa82b31b344f /markup/pod/live-manual/media/text/es/appendix_style-guide.ssi
track document samples used
Diffstat (limited to 'markup/pod/live-manual/media/text/es/appendix_style-guide.ssi')
-rw-r--r--markup/pod/live-manual/media/text/es/appendix_style-guide.ssi379
1 files changed, 379 insertions, 0 deletions
diff --git a/markup/pod/live-manual/media/text/es/appendix_style-guide.ssi b/markup/pod/live-manual/media/text/es/appendix_style-guide.ssi
new file mode 100644
index 0000000..f4caba7
--- /dev/null
+++ b/markup/pod/live-manual/media/text/es/appendix_style-guide.ssi
@@ -0,0 +1,379 @@
+: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