18/03/10 1

Aurelio García Cerrada

Escuela Técnica Superior de Ingeniería

RECOMENDACIONES PARA LA

REDACCIÓN DE DOCUMENTOS

TÉCNICOS

Aurelio García Cerrada

Escuela Técnica Superior de

Ingeniería

18/03/10 2

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/10 3

Preliminares

Consideraciones “antes” de ponerse a escribir

18/03/10 4

¿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/10 5

¿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/10 6

¿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/10 7

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/10 8

¿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/10 9

¿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/10 10

¿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/10 11

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/10 12

La estructura del documento

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

18/03/10 13

La estructura

• El índice (tabla de contenidos)

• Una estructura lógica

• Recomendaciones generalmente aceptadas

• Las secciones más comunes

• Los apéndices

18/03/10 14

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/10 15

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, por ejemplo, porque ayuda a tener una mejor perspectiva del documento

18/03/10 16

Una estructura adecuada

Introducción

Antecedentes, contexto

Detalles técnicos

Resultados

Discusión y Conclusiones

18/03/10 17

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/10 18

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/10 19

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/10 20

Más secciones típicas

• Resumen (Abstract), ejemplo:

18/03/10 21

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/10 22

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/10 23

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/10 24

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/10 25

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/10 26

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/10 27

Otras cuestiones

La forma también es importante

18/03/10 28

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/10 29

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/10 30

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/10 31

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/10 32

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/10 33

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/10 34

Procesadores de texto

Pueden mencionarse dos muy populares:

• Microsoft word

• Latex

18/03/10 35

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/10 36

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/10 37

Finalmente

El control de calidad

18/03/10 38

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/10 39

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/10 40

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/10 41

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/10 42

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/10 43

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/10 44

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/10 45

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/)