Revisión de estilo y trabajo
editorial en documentos técnicos
de informática
Luis Fernández y María José Rueda
La documentación como producto
-
El objetivo de cualquier documento es satisfacer la necesidad
de:
-
Comunicación desde el autor hacia los lectores
-
En el caso de la documentación técnica, podemos
señalar que:
-
Resulta clave para el trabajo de los equipos que habitualmente cuenta con
un gran número de miembros
-
Dada la gran rotación del personal técnico, es esencial contar
con documentación de buena calidad para una coordinación
efectiva
-
En esta ponencia, limitaremos el estudio de los documentos
técnicos de informática según las siguientes indicaciones:
-
Dejaremos aparte el caso especial de los manuales de usuario puesto que
el conjunto de lectores a los que va dirigido es muy amplio y no se puede
asegurar que tengan unos mínimos conocimientos técnicos.
-
Asumiremos que el autor redactará un documento que contendrá
información y conocimientos que domina
-
Muchos documentos técnicos deben incluir elementos no estrictamente
textuales que también se deben controlar de alguna manera
Problemas
-
Una de las consecuencias menos deseables de una mala redacción
de documentos es que los documentos llegan a ser:
-
Ilegibles
-
Incomprensibles
-
Ambiguos
Un caso de documento incomprensible, ambiguo e ¿ilegible?
La orden ejecutiva 10.358 fijaba en el caso de un empleado
cuya semana laboral variara de la normal semana de lunes a viernes, que
la fiesta del trabajo y el día de acción de gracias se contemplaran
cada uno en el siguiente día laboral cuando la fiesta cayese en
un día fuera de la semana básica laboral regular del empleado.
Ahora, cuando la fiesta del trabajo, el día de acción de
gracias o cualquiera de las nuevas fiestas en lunes caiga fuera de la semana
laboral básica del empleado, su fiesta será el día
laboral inmediatamente precedente cuando el día no laborable en
el que caiga la fiesta sea el segundo día no laborable o el día
no laborable designado como el día de descanso del empleado en lugar
del sábado. Cuando el día no laborable en el que cae la fiesta
es el primer día no laborable o el día no laborable designado
como día de descanso del empleado en lugar del sábado, la
fiesta prescrita se moverá al siguiente día laborable sucesivo.
Causas
-
Los técnicos suelen ser malos comunicadores y así
se reconoce en diversas obras (por ejemplo, [Lamb, 1988]).
Frente a este problema cabe adoptar dos tipos de iniciativas:
1. Mejora de la capacidad de comunicación oral y escrita de los
técnicos mediante la formación o el establecimiento de alguna
lista de normas sencillas. Así, se pueden mencionar como ejemplos
de este tipo de medidas:
-
Los módulos de formación en redacción
técnica para ingenieros de software del SEI (Software Engineering
Institute) de EE.UU. [Glass, 1988]
-
Los documentos explicativos que producen ciertas multinacionales
para que sirvan de guía de redacción (en este caso, en inglés)
a los empleados de sus distintas delegaciones [ABB, 1988]
2. Incorporación de diversas medidas de control para los documentos
más importantes:
-
Revisión ortotipográfica
-
Revisión de estilo
-
Lectura de pruebas
Revisión de ortografía
-
En este ámbito de trabajo se presupone que el autor
tiene conocimientos suficientes de las reglas ortográficas y gramaticales
-
Siempre existe el apoyo de las utilidades de corrección
ortográfica y de gramática de los procesadores de texto (por
ejemplo, las de Word). Sin embargo, hay que ser consciente de las limitaciones
de estos programas:
-
En ortografía: una de las principales limitaciones surge de que
no se distingue las distintas variantes de las palabras, ya que lo único
que se comprueba es si cada palabra pertenece o no a la lista de palabras
correctas: por ejemplo, "hay/ahí/ay" o "módulo/modulo/moduló"
-
En gramática: aunque se supone que se pueden detectar fallos en
concordancias en las frases, sin embargo no siempre se realiza bien este
control. Por ejemplo, el siguiente caso se marca como erróneo porque
se supone que "pueden" no coincide en número con "mantenimiento":
"Algunos de los factores que afectan a la productividad en el mantenimiento
pueden ser consecuencia [...]". Otra limitación consiste en la falta
de control de la semántica de las frases o de sus elementos.
-
En el caso de requerir el empleo de la utilidad de Sinónimos/antónimos,
se puede llegar a ver curiosas acepeciones de las palabras. Por ejemplo,
al pedir sinónimos de "ansiosa" nos aparece como primera opción
"ninfómana (adjetivo)".
-
Por último, hay que destacar que en el diccionario empleado en Word,
faltan palabras del diccionario de la Real Academia (por ejemplo, "compleción")
y aparecen términos no aceptados.
Legibilidad y claridad
-
Se trata de comprobar si es legible el texto y si lo que
se quiere comunicar llega con claridad al lector.
-
Para crear textos legibles y claros se recomienda se pueden
seguir las siguientes recomendaciones:
-
Se utilizarán párrafos con frases cortas.
-
Se preferirá el uso de la voz activa sobre la voz pasiva impersonal.
A su vez, se preferirá la voz impersonal sobre la pasiva.
-
Se deberá cuidar la puntuación correcta.
-
Se deberá cuidar el uso de tecnicismos (anglicismos, sobre todo)
y neologismos. En cualquier caso, se trata de mantener la coherencia en
la traducción de términos extranjeros y en su uso. Podemos
encontrar casos como el término inglés "actual" que
se debe traducir como "real" y no caer en la tentación de traducir
por "actal". Otro ejemplo es el neologismo "completitud" que es innecesario
ya que existe "compleción". Otra mala traducción consiste
en asignar el término "requerimiento" a "requirement" en
vez de usar el más lógico "requisito".
-
Para el lector también resulta más fácil de entender
las frases que mantienen el órden sintáctico clásicos
en los elementos de oración: Sujeto + Verbo + Complementos (Directo
+ Indirecto + Circunstancial).
Inteligibilidad
-
Otra propiedad importante que trata de evaluar si se entiende
el texto o si se hace entender el autor. Para ello, se debe evitar caer
en los siguientes problemas:
-
Ambigüedad.
-
"Ambos ficheros se controlan mediante un registro de control
de ficheros": ¿De qué se trata? ¿De un registro para
dos ficheros o de que cada fichero tiene un registro?
-
Confusión.
-
Expresiones negativas: "No es probable que no ocurra algo
que no sea distinto a dicha situación"
-
Coherencia en todo el texto.
-
Hay que usar el mismo término para designar el mismo
concepto a lo largo de todo el texto. Se deben definir los términos
la primera vez que aparezcan.
-
Compleción: información completa.
-
Es necesario definir las abreviaturas o siglas en su 1ª
aparición. Es recomendable incluir una lista final con las definiciones
de abreviaturas y siglas.
-
Redundancia.
-
Hay que evitar las palabras que no aportan nada, así
como la repetición de ideas o frases.
Tipografía y diseño
-
Se recomienda mantener una coherencia en el uso de marcas
tipográficas para conservar su valor distintivo, de tal manera que
cada marca (cursiva, negra, comillas, mayúsculas, subrayado) ofrezca
un significado propio. Por ejemplo, poner siempre en cursiva las palabras
extranjeras.
-
Hay que cuidar el establecimiento de apartados y subapartados
para estructurar el texto:
-
Existen normas y guías para fijar los niveles, sangrados y numeración
(por ejemplo, la norma UNE 50-132 ) de los títulos de apartados
y subapartados.
-
Es recomendable limitar el número de subniveles de apartados para
evitar que el lector pierda la perspectiva de la estructura del texto.
-
En las ilustraciones se debe prestar atención a dos
aspectos que inciden en su utilidad:
-
La información en el pie de la ilustración debería
consistir en un título que no sea ni explicativo ni descriptivo.
-
Es necesario que toda ilustración sea mencionada mediante referencia
en el texto.
Uso de referencias
-
Las referencias a otras obras son esenciales para la mayoría
de los documentos, aunque sólo sea para mencionar información
que no se desea duplicar en el texto que se está redactando. Es
importante establecer un sistema adecuado de referencias. Para ellos se
puede recurrir a la norma UNE 50-104-94.
-
En el caso de ser necesario insertar citas textuales en el
texto, se recomienda:
-
Cita breve: debería aparecer intercalada con comillas en el cuerpo
del texto.
-
Cita extensa (tres líneas o más): debería aparecer
en un párrafo aparte, sangrado y en un cuerpo de letra distinto.
Que inventen ellos
-
Muchas veces pensamos que debemos inventar normas y convenciones
de redacción para los documentos técnicos. No obstante, lo
cierto es que existen muchas obras en las que los expertos en filología
o los dedicados a la redacción y creación de documentos ya
han abordado muchos de los problemas que queremos resolver. Conviene conocer
lo que hay antes de embarcarse en inventar nuevas normas o guías.
-
Lista de normas y recomendaciones que se pueden consultar
para obtener más detalles sobre redacción técnica:
-
Guía para redacción de artículos científicos,
UNESCO PGI-83 WS 10.
-
ISO 5966:1982 (UNE 50-135): Documentación-Presentación de
informes científicos y técnicos.
-
Normas ISO/UNE (en especial las de la serie 50).
-
Guías de contenido y estructura:
-
Por ejemplo, los estándares de IEEE para documentos
técnicos
-
Ayer y Patrinostro, Documenting the software development process,
McGraw-Hill
-
Price y Korman, How to communicate technical information, Benjamin/Cummings
-
Guías y recomendaciones generales sobre ortografía
y lengua española:
-
El País, Libro de estilo
-
ABC, Libro de estilo
-
M. Seco, Diccionario de dudas y dificultades de la lengua española
-
J. Martínez de Sousa, Diccionario de tipografía y del
libro
-
M. Gómez Torrego, Manual de español correcto
-
M. Moliner, Diccionario de uso del español
Referencias
-
[ABB, 1988] Asea Brown Boveri, Documentation
Standards. Writers Guide, ABB, 1988.
-
[Glass, 1988] R.L.Glass, Curriculum
Module SEI-CM-18-1.0. An overview of technical communication for software
engineers, Software Engineering Institute, 1988.
-
[Lamb, 1988] D.A.Lamb, Software engineering.
Planning for change, Prentice-Hall, 1988.
|