18/03/101

Aurelio García Cerrada

Escuela Técnica Superior de Ingeniería

RECOMENDACIONES PARA LAREDACCIÓN DE DOCUMENTOS TÉCNICOS

Aurelio García CerradaEscuela Técnica Superior de

Ingeniería

18/03/102

Contenido

• Preliminares.

• Tipos de documentos técnicos

• Estructura en el “modelo habitual”

• Aspectos relacionados con la forma

• Alternativas al modelo habitual

• El procesador de texto

• Control de calidad

• Resumen

18/03/103

Preliminares

Consideraciones “antes” de ponerse a escribir

18/03/104

¿Qué es un documento técnico?

“La presentación sistemática de la evidencia y/o la información sobre una situación, problema o necesidad en el ámbito de la ciencia o la tecnología”

[Australian Training Products Ltd]

18/03/105

¿Qué es un documento técnico?

• La misión fundamental e inexcusable de un Doc. Tec. es “transmitir información”.

• Antes debemos haber generado-obtenido esa información.

• El entretenimiento del lector (aunque deseable) es un aspecto accesorio.

18/03/106

¿Qué es un documento técnico?

• Hay muchos tipos de Doc.Tec.: – Documento de especificaciones–Manuales de usuario– Código para ordenador– Estudios de viabilidad– Artículos (divulgación o investigación)– Propuestas– Ofertas– Tesis, libros, etc.

18/03/107

Muchos documentos y poco tiempo

• Los puntos clave y las conclusiones principales tienen que estar muy accesibles

• Debe considerarse un resumen al principio

• No todo el mundo tiene tiempo para leer todo el documento

18/03/108

¿Por qué hay que escribir documentos técnicos?

• Para asegurar la transmisión del conocimiento (continuación del proyecto, avances tecnológicos, etc.)

• Es la primera forma de registro de la “autoría intelectual” de cualquier cosa

• En algunas profesiones es una forma muy aceptada de evaluación

18/03/109

¿Por qué hay que escribir documentos técnicos?

Una anécdota:

[Plank empleo un esfuerzo considerable (1875-1891) en su teoría sobre la entropía (antes de su teoría cuántica) porque Gibbs (que ya había hecho ese trabajo) lo escribió para un medio con poca divulgación]

(Bryson, 2004)

18/03/1010

¿Para quién se escribe?

• No se puede escribir para que todo el mundo lo entienda

• Desde el principio hay que identificar los posibles (o deseables) lectores

• ¿Conocen el tema de forma general?. ¿Son expertos?. ¿Conocen el detalle del trabajo que se describe?, ¿sólo un poco? …

18/03/1011

La longitud prevista para el doc.

• ¿20 Págs.. o 200 Págs..?

• Un documento corto necesita más trabajo de planificación

• Algunos tipos de documentos tienen una longitud máxima establecida (artículos, tesis, proyectos fin de carrera, …)

• Baltasar Gracián: “Lo bueno si breve …”

18/03/1012

La estructura del documento

El modelo “convencional” es el más seguro para los escritores noveles

18/03/1013

La estructura

• El índice (tabla de contenidos)

• Una estructura lógica

• Recomendaciones generalmente aceptadas

• Las secciones más comunes

• Los apéndices

18/03/1014

El índice

• Escribir un “índice” para el documento puede ser un buen momento para darle una estructura adecuada

• Una buena estructura ahorrará mucho tiempo después

• Puede llevar unos cuantos días• Se debe reflejar el mayor nivel de detalle posible• Puede modificarse después si es necesario

18/03/1015

Una estructura adecuada

• De lo general a lo particular• Primero los antecedentes y después el material

técnico• El documento debe “llevar” al lector de forma

lógica a las conclusiones• La estructura del doc. no refleja la secuencia

temporal de escritura• No es raro escribir la introducción al final.

Ayuda a tener una mejor perspectiva del documento

18/03/1016

Una estructura adecuada

Introducción

Antecedentes, contexto

Detalles técnicos

Resultados

Discusión y Conclusiones

18/03/1017

Recomendaciones generales

• La primera sección “seria” es la introducción• En ella se plantean (explícitamente o no) las

preguntas que se responderán en “las conclusiones”

• Los “hechos” y las medidas se separan de las opiniones y las interpretaciones

• Es frecuente referirse al trabajo hecho por otros antes

• Las secciones, sub-secciones, apartados (y algunas veces los párrafos) se numeran

18/03/1018

Las secciones más comunes

• Una página para el título (logo, autores, fecha, etc.)

• Una dedicatoria (algunas veces podemos ser sentimentales)

• Una declaración (copyright, autenticidad, …)

• Agradecimientos (a todos aquellos que han ayudado sin participar en el documento)

• Índice

18/03/1019

Más secciones típicas

• Resumen (Abstract):

“Resume” el documento completo. 300 palabras es una medida que suele usarse, por ejemplo, en artículos técnicos. Algunas veces es susceptible de publicarse como presentación del documento o como reclamo.

18/03/1020

Introducción

• Presenta el trabajo realizado• Establece las motivaciones del trabajo y su

contexto (relación con otros trabajos)• Plantea, explícita o implícitamente, las

preguntas que se van a resolver a lo largo del documento

• Presenta, a grandes rasgos, el contenido del documento

18/03/1021

El “cuerpo” principal del documento

• Aquí se presenta la mayor parte del material técnico• Teoría, hipótesis, método de trabajo, resultados,

discusión de esos resultados• Aquí se pondrán las tablas, las figuras, los circuitos,

…. para facilitar la comunicación• Se comparan hipótesis con resultados, se comentan

opiniones y se especula con el alcance de los resultados del trabajo

18/03/1022

Conclusiones

• Presentan el resumen de los principales resultados y las conclusiones que de ellos pueden sacarse

• Deben deducirse del trabajo y resultados presentados en el cuerpo principal del documento.

• Debe cuidarse su redacción. Probablemente es la única parte del documento que la mayor parte de la gente leerá más de una vez

• Esta sección será decisiva en la impresión que el lector tenga del trabajo completo

18/03/1023

Apéndices

• Contienen cosas importantes que obstaculizarían la lectura fluida del resto del documento.

• Parámetros, demostraciones matemáticas, extracto de normativas aplicables, planos detallados, etc.

• No se recomienda para hojas de características

18/03/1024

Lista de referencias

• Durante TODO el documento es imprescindible referenciar el trabajo de “otros” sobre el que hemos construido el “nuestro”

• Al final se recogen, ordenadas de alguna forma, todas esas referencias con los datos necesarios para que el lector interesado pueda encontrarlas

• El plagio es inaceptable pero, además, …Una buena utilización de las referencias mejora la credibilidad de nuestro trabajo

• El receptor final del documento puede tener normas explicitas sobre cómo se hacen las referencias a trabajos anteriores

18/03/1025

Referencias dentro de nuestro documento

• Para evitar repeticiones, frecuentemente es necesario referenciar material dentro del propio documento

• Todo material susceptible de ser referenciado debe llevar un nombre inequívoco

• Por ese motivo se numeran los capítulos, las secciones, las figuras, las tablas, las ecuaciones, los teoremas, etc.

18/03/1026

Otras cuestiones

La forma también es importante

18/03/1027

El lenguaje• Suele escribirse en forma impersonal y con frases

cortas

• En Inglés se usa frecuentemente la voz pasiva (y sólo aquí)

• Se revisa la ortografía y la gramática concienzudamente

• En Inglés, por ejemplo, debe evitarse partir las palabras, porque es un tema difícil

18/03/1028

Figuras, tablas y ecuaciones I

• TODAS las figuras deben numerarse de forma consecutiva. Cada figura debe llevar un pie explicativo

• Lo mismo con TODAS las tablas• Las figuras son excelentes para comparar tendencias,

dar la visión general de la organización de las partes, etc.

• Las tablas sirven para comparaciones numéricas más detalladas

18/03/1029

Figuras, tablas y ecuaciones II

• Las ecuaciones son concisas y dicen mucho en poco terreno. No hay que tener miedo de usarlas

• Las ecuaciones también se numeran para futuras referencias

• El texto llena el espacio entre ecuaciones, tablas y figuras. Es el hilo conductor de la información

18/03/1030

Ventajas del modelo habitual

• El lector sabrá qué esperar y dónde buscar las cosas• La estructura del documento es clara y fácil de

entender• Al ser muy rígida, es más fácil para los escritores

menos experimentados• No siempre hay que incluir todas las secciones que se

han descrito

18/03/1031

Alternativas al modelo habitual

• Si se describen distintos experimentos con un propósito común … podría ser conveniente explicar completamente cada experimento por separado y añadir secciones comunes (Introducción, Comparaciones, etc.)

• A veces los nombres convencionales de las secciones (Introducción, Resultados ..) se sustituyen por “Titulares”. El lector sabrá de qué va el informe y los resultados leyendo el índice.

18/03/1032

Más alternativas

• En ocasiones, es conveniente poner las conclusiones al principio. Así, seguro que se leen y el lector puede tenerlas en mente mientras sigue el resto del documento.

• En documentos dedicados a la revisión de procedimientos, por ejemplo, podría ser útil poner una sección para cada uno de ellos y algunas secciones comunes (Introducción y Comparación, por ejemplo)

18/03/1033

Procesadores de texto

Pueden mencionarse dos muy populares:

• Microsoft word• Latex

18/03/1034

Microsoft word

• WYSIWYG?: What you see is what you get?• WYSIWYWLTG!: What you see is what you

would like to get!• Fácil de aprender rápidamente• Difícil para mantener las referencias cruzadas

dentro del documento o a la lista de referencias• El manejo de documentos largos es complicado

18/03/1035

Latex

• YCOGWYAGTG!: You can only guess what you are going to get! (ASCII con comandos como el HTML)

• WCINAW!: Who cares! it’s nice, anyway! (sobre todo las ecuaciones y las figuras)

• Es perfecto para manejar referencias cruzadas y la lista de referencias

• Maneja perfectamente documentos largos (libros, tesis, …)

• Difícil de aprender pero es gratis

18/03/1036

Finalmente

El control de calidad

18/03/1037

Control por el autor

• El documento debe revisarse antes de ponerlo en circulación

• El autor debería volver a leer el documento tratando de olvidar quién lo ha escrito

• TODOS los defectos de forma deben corregirse en este momento

18/03/1038

Un amigo desinteresado

• Es buena idea que alguien ajeno al grupo de autores lea y comente el documento

• Este paso es particularmente importante si los autores escriben en una lengua distinta de la materna

18/03/1039

El supervisor• El supervisor del equipo también tendrá

responsabilidades en el documento final• Si se han limado otros defectos, puede concentrarse

en hacer comentarios útiles sobre el contenido técnico

• ¡Si lo devuelve sin correcciones es que … no se lo ha leído!

• Algunos llegarán a ser supervisores algún día y podrían no necesitar estas recomendaciones

18/03/1040

Resumen y conclusiones

• Hay que escribir para transmitir información

• Aunque el lector puede leer, volver a leer, saltar a otra sección, volver atrás, etc., no hay que presumir que tiene mucho tiempo

• Un buen documento hay que planearlo

18/03/1041

Resumen y conclusiones (cont.)

• Hay una “forma de escribir” aceptada en la comunidad científico-técnica– Se plantea el problema y se pone en contexto– Se describe el trabajo realizado y los resultados– Se escriben las conclusiones

• Hay que cuidar el fondo y las formas• Incluso debe escogerse con cuidado el procesador

de texto que se va a utilizar • El control de calidad debe ser exhaustivo y

completo

18/03/1042

Referencias (I)• Australian Training Products Ltd. “Writing technical

documents NCS017”. 1996. http://www.atpl.net.au/sample/pdf/atpsample_2655.pdf.

• Boone, K. “How to write a report”. Sun Microsystems UK. http://www.kevinboone.com/howto_report.html.

• Bryson, B. A Short History of Nearly Everything. A Black Swan book. 2004.

• Li, V.O.K. “Hints on writing technical papers and making presentations” IEEE Transactions on Education, vol. 42, no. 2, May 1999, pp.134-137

• Nonash University (Language and learning on-line) “Writing technical reports”. http://www.monash.edu.au/lls/llonline/writing/engineering/technical-report/index.xml

18/03/1043

Referencias II

• Ramón y Cajal, S. Reglas y Consejos Sobre Investigación Científica. Colección Austral, Espasa Calpe, Ed. 13; 1995.

• Ringwood, J. “Hints on technical report writing”. School of Electronic Engineering. Dublin City Univ., 1999 http://odtl.dcu.ie/wp/1999/odtl-1999-03.html.

18/03/1044

El escritor profesional

Technical author training and report-writing courses

You can earn 750€+ per week as a freelance technical author!

(http://www.estontrg.com/)