Asociación de Técnicos de Informática.Grupos de TrabajoNoticias de ATIServicio ATInetPublicaciones de ATIFormación: Catálogo y NovedadesBolsa de Trabajo Ayuda

 
I Jornada  sobre Lengua e Informática
 
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.


 

 I Jornada  sobre Lengua e Informática

 
 
Última actualización: 30 de noviembre de 1999 
Sugerencias, comentarios, noticias, advertencias, ...info@ati.es
Mejor con cualquier visualizadorHTML 3.2


Sitio Web creado en 1994 por ATI (Asociación de Técnicos de Informática)
Este es el más antiguo de los webs asociativos de España