Post on 24-Mar-2020
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 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 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 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 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 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.