RECOMENDACIONES PARA LA REDACCIÓN DE … documentos-tecnicos-nov-07_2.pdf · • Lo mismo con...

RECOMENDACIONES PARA LA RECOMENDACIONES PARA LA REDACCIÓN DE DOCUMENTOS REDACCIÓN DE DOCUMENTOS

TÉCNICOSTÉCNICOS

Aurelio García CerradaAurelio García Cerrada

Dept. de Electrónica y Automática e Instituto de Dept. de Electrónica y Automática e Instituto de Investigación Tecnológica. ETS de IngenieríaInvestigación Tecnológica. ETS de Ingeniería

Univ. Pontificia Comillas de MadridUniv. Pontificia Comillas de Madrid

Noviembre 2007 Redacción de docs. técnicos 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

PreliminaresPreliminares

Consideraciones “antes” de ponerse a escribirConsideraciones “antes” de ponerse a escribir


¿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]


¿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.


Tipos de documentos técnicos• 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.– Cuadernos de laboratorio


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


¿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 (cantidad y calidad de los docs. escritos)


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


¿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? …


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 …”

La estructura del documentoLa estructura del documento

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


La estructura

• El índice (tabla de contenidos)• Una estructura lógica

• Recomendaciones generalmente aceptadas• Las secciones más comunes

• Los apéndices


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


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


Una estructura adecuada

Introducción

Antecedentes, contexto

Detalles técnicos

Resultados

Discusión y Conclusiones


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


Las secciones más comunes• Una página para el título (logo, autores, fecha, etc.)

• Una dedicatoria (podemos ser ingeniosos, sentimentales, atrevidos …)

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

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

• Índice


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.


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


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


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


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


Lista de referencias• Durante TODO el documento es imprescindible referenciar el

trabajo de “otros” sobre el que hemos construido el “nuestro”• Al final se re c oge n, o rde nadas de alguna forma, todas esas

referencias con los datos ne c e s ario s para que el lector interesado pueda encontrarlas

• El plag io e s inac e ptable pe ro , ade má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


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.

Otras cuestionesOtras cuestiones

La forma también es importanteLa forma también es importante


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


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


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


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


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.


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)


Procesadores de texto

Pueden mencionarse dos muy populares:

• Microsoft word• Latex


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


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

FinalmenteFinalmente

El control de calidadEl control de calidad


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


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


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

leido!• Algunos llegarán a ser supervisores algún día y podrían

no necesitar estas recomendaciones


Resumen y conclusiones (I)

• 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


Resumen y conclusiones (II) • 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


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


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.


El escritor profesionalTechnical author training and report-writing courses

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

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

RECOMENDACIONES PARA LA REDACCIÓN DE … documentos-tecnicos-nov-07_2.pdf · • Lo mismo con...

Documents

Transcript of RECOMENDACIONES PARA LA REDACCIÓN DE … documentos-tecnicos-nov-07_2.pdf · • Lo mismo con...