Post on 21-Jul-2019
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
Noviembre 2007 Redacción de docs. técnicos 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]
Noviembre 2007 Redacción de docs. técnicos 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.
Noviembre 2007 Redacción de docs. técnicos 6
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
Noviembre 2007 Redacción de docs. técnicos 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
Noviembre 2007 Redacción de docs. técnicos 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 (cantidad y calidad de los docs. escritos)
Noviembre 2007 Redacción de docs. técnicos 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)
Noviembre 2007 Redacción de docs. técnicos 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? …
Noviembre 2007 Redacción de docs. técnicos 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 …”
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
Noviembre 2007 Redacción de docs. técnicos 13
La estructura
• El índice (tabla de contenidos)• Una estructura lógica
• Recomendaciones generalmente aceptadas• Las secciones más comunes
• Los apéndices
Noviembre 2007 Redacción de docs. técnicos 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
Noviembre 2007 Redacción de docs. técnicos 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
Noviembre 2007 Redacción de docs. técnicos 16
Una estructura adecuada
Introducción
Antecedentes, contexto
Detalles técnicos
Resultados
Discusión y Conclusiones
Noviembre 2007 Redacción de docs. técnicos 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
Noviembre 2007 Redacción de docs. técnicos 18
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
Noviembre 2007 Redacción de docs. técnicos 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.
Noviembre 2007 Redacción de docs. técnicos 20
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
Noviembre 2007 Redacción de docs. técnicos 21
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
Noviembre 2007 Redacción de docs. técnicos 22
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
Noviembre 2007 Redacción de docs. técnicos 23
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
Noviembre 2007 Redacción de docs. técnicos 24
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
Noviembre 2007 Redacción de docs. técnicos 25
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.
Noviembre 2007 Redacción de docs. técnicos 27
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
Noviembre 2007 Redacción de docs. técnicos 28
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
Noviembre 2007 Redacción de docs. técnicos 29
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
Noviembre 2007 Redacción de docs. técnicos 30
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
Noviembre 2007 Redacción de docs. técnicos 31
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.
Noviembre 2007 Redacción de docs. técnicos 32
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)
Noviembre 2007 Redacción de docs. técnicos 33
Procesadores de texto
Pueden mencionarse dos muy populares:
• Microsoft word• Latex
Noviembre 2007 Redacción de docs. técnicos 34
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
Noviembre 2007 Redacción de docs. técnicos 35
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
Noviembre 2007 Redacción de docs. técnicos 37
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
Noviembre 2007 Redacción de docs. técnicos 38
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
Noviembre 2007 Redacción de docs. técnicos 39
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
Noviembre 2007 Redacción de docs. técnicos 40
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
Noviembre 2007 Redacción de docs. técnicos 41
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
Noviembre 2007 Redacción de docs. técnicos 42
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
Noviembre 2007 Redacción de docs. técnicos 43
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.