Post on 04-Nov-2018
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/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/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/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/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.