RECOMENDACIONES PARA LA REDACCIN DE DOCUMENTOS TCNICOS

Aurelio Garca Cerrada Dept. de Electrnica y Automtica e Instituto de Investigacin Tecnolgica. ETS de Ingeniera Univ. Pontificia Comillas de Madrid

Contenido
Preliminares. Tipos de documentos tcnicos Estructura en el modelo habitual Aspectos relacionados con la forma Alternativas al modelo habitual El procesador de texto Control de calidad Resumen

Noviembre 2007

Redaccin de docs. tcnicos

Preliminares
Consideraciones antes de ponerse a escribir

Qu es un documento tcnico?
La presentacin sistemtica de la evidencia y/o la informacin sobre una situacin, problema o necesidad en el mbito de la ciencia o la tecnologa [Australian Training Products Ltd]

Noviembre 2007

Redaccin de docs. tcnicos

Qu es un documento tcnico?
La misin fundamental e inexcusable de un Doc. Tec. es transmitir informacin. Antes debemos haber generado-obtenido esa informacin. El entretenimiento del lector (aunque deseable) es un aspecto accesorio.

Noviembre 2007

Redaccin de docs. tcnicos

Tipos de documentos tcnicos

Hay muchos tipos de Doc.Tec.:
Documento de especificaciones Manuales de usuario Cdigo para ordenador Estudios de viabilidad Artculos (divulgacin o investigacin) Propuestas, Ofertas Tesis, libros, etc. Cuadernos de laboratorio
Noviembre 2007 Redaccin de docs. tcnicos 6

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

Redaccin de docs. tcnicos

Por qu hay que escribir documentos tcnicos?

Para asegurar la transmisin del conocimiento (continuacin del proyecto, avances tecnolgicos, etc.) Es la primera forma de registro de la autora intelectual de cualquier cosa En algunas profesiones es una forma muy aceptada de evaluacin (cantidad y calidad de los docs. escritos)
Noviembre 2007 Redaccin de docs. tcnicos 8

Por qu hay que escribir documentos tcnicos?

Una ancdota: [Plank empleo un esfuerzo considerable (1875-1891) en su teora sobre la entropa (antes de su teora cuntica) porque Gibbs (que ya haba hecho ese trabajo) lo escribi para un medio con poca divulgacin] (Bryson, 2004)

Noviembre 2007

Redaccin de docs. tcnicos

Para quin 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?, slo un poco?

Noviembre 2007

Redaccin de docs. tcnicos

10

La longitud prevista para el doc.

20 Pgs.. o 200 Pgs..? Un documento corto necesita ms trabajo de planificacin Algunos tipos de documentos tienen una longitud mxima establecida (artculos, tesis, proyectos fin de carrera, ) Baltasar Gracin: Lo bueno si breve
Noviembre 2007 Redaccin de docs. tcnicos 11

La estructura del documento

El modelo convencional es el ms seguro para los escritores noveles

La estructura
El ndice (tabla de contenidos) Una estructura lgica Recomendaciones generalmente aceptadas Las secciones ms comunes Los apndices

Noviembre 2007

Redaccin de docs. tcnicos

13

El ndice
Escribir un ndice para el documento puede ser un buen momento para darle una estructura adecuada Una buena estructura ahorrar mucho tiempo despus Puede llevar unos cuantos das Se debe reflejar el mayor nivel de detalle posible Puede modificarse despus si es necesario

Noviembre 2007

Redaccin de docs. tcnicos

14

Una estructura adecuada

De lo general a lo particular Primero los antecedentes y despus el material tcnico El documento debe llevar al lector de forma lgica a las conclusiones La estructura del doc. no refleja la secuencia temporal de escritura: no es raro escribir la introduccin al final, por ejemplo, porque ayuda a tener una mejor perspectiva del documento

Noviembre 2007

Redaccin de docs. tcnicos

15

Una estructura adecuada

Introduccin Antecedentes, contexto

Detalles tcnicos

Resultados

Discusin y Conclusiones
Noviembre 2007 Redaccin de docs. tcnicos 16

Recomendaciones generales
La primera seccin seria es la introduccin En ella se plantean (explcitamente o no) las preguntas que se respondern 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 prrafos) se numeran

Noviembre 2007

Redaccin de docs. tcnicos

17

Las secciones ms comunes

Una pgina para el ttulo (logo, autores, fecha, etc.) Una dedicatoria (podemos ser ingeniosos, sentimentales, atrevidos ) Una declaracin (copyright, autenticidad, ) Agradecimientos (a todos aquellos que han ayudado sin participar en el documento) ndice

Noviembre 2007

Redaccin de docs. tcnicos

18

Ms secciones tpicas
Resumen (Abstract):
Resume el documento completo. 300 palabras es una medida que suele usarse, por ejemplo, en artculos tcnicos. Algunas veces es susceptible de publicarse como presentacin del documento o como reclamo.

Noviembre 2007

Redaccin de docs. tcnicos

19

Introduccin
Presenta el trabajo realizado Establece las motivaciones del trabajo y su contexto (relacin con otros trabajos) Plantea, explcita o implcitamente, las preguntas que se van a resolver a lo largo del documento Presenta, a grandes rasgos, el contenido del documento

Noviembre 2007

Redaccin de docs. tcnicos

20

El cuerpo principal del documento

Aqu se presenta la mayor parte del material tcnico Teora, hiptesis, mtodo de trabajo, resultados, discusin de esos resultados Aqu se pondrn las tablas, las figuras, los circuitos, . para facilitar la comunicacin Se comparan hiptesis con resultados, se comentan opiniones y se especula con el alcance de los resultados del trabajo

Noviembre 2007

Redaccin de docs. tcnicos

21

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 redaccin. Probablemente es la nica parte del documento que la mayor parte de la gente leer ms de una vez Esta seccin ser decisiva en la impresin que el lector tenga del trabajo completo

Noviembre 2007

Redaccin de docs. tcnicos

22

Apndices
Contienen cosas importantes que obstaculizaran la lectura fluida del resto del documento. Parmetros, demostraciones matemticas, extracto de normativas aplicables, planos detallados, etc. No se recomienda para hojas de caractersticas

Noviembre 2007

Redaccin de docs. tcnicos

23

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 o g e n, o rde nadas de alguna forma, todas esas referencias con los datos ne c e s arios para que el lector interesado pueda encontrarlas El plag io e s inac e ptable pe ro, ade m s , Una buena utilizacin de las referencias mejora la credibilidad de nuestro trabajo El receptor final del documento puede tener normas explicitas sobre cmo se hacen las referencias a trabajos anteriores

Noviembre 2007

Redaccin de docs. tcnicos

24

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 inequvoco Por ese motivo se numeran los captulos, las secciones, las figuras, las tablas, las ecuaciones, los teoremas, etc.

Noviembre 2007

Redaccin de docs. tcnicos

25

Otras cuestiones
La forma tambin es importante

El lenguaje
Suele escribirse en forma impersonal y con frases cortas En Ingls se usa frecuentemente la voz pasiva (y slo aqu) Se revisa la ortografa y la gramtica concienzudamente En Ingls, por ejemplo, debe evitarse partir las palabras, porque es un tema difcil

Noviembre 2007

Redaccin de docs. tcnicos

27

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 visin general de la organizacin de las partes, etc. Las tablas sirven para comparaciones numricas ms detalladas

Noviembre 2007

Redaccin de docs. tcnicos

28

Figuras, tablas y ecuaciones II

Las ecuaciones son concisas y dicen mucho en poco terreno. No hay que tener miedo de usarlas Las ecuaciones tambin se numeran para futuras referencias El texto llena el espacio entre ecuaciones, tablas y figuras. Es el hilo conductor de la informacin

Noviembre 2007

Redaccin de docs. tcnicos

29

Ventajas del modelo habitual

El lector sabr qu esperar y dnde buscar las cosas La estructura del documento es clara y fcil de entender Al ser muy rgida, es ms fcil para los escritores menos experimentados No siempre hay que incluir todas las secciones que se han descrito
Noviembre 2007 Redaccin de docs. tcnicos 30

Alternativas al modelo habitual

Si se describen distintos experimentos con un propsito comn podra ser conveniente explicar completamente cada experimento por separado y aadir secciones comunes (Introduccin, Comparaciones, etc.) A veces los nombres convencionales de las secciones (Introduccin, Resultados ..) se sustituyen por Titulares. El lector sabr de qu va el informe y los resultados leyendo el ndice.

Noviembre 2007

Redaccin de docs. tcnicos

31

Ms 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 revisin de procedimientos, por ejemplo, podra ser til poner una seccin para cada uno de ellos y algunas secciones comunes (Introduccin y Comparacin, por ejemplo)

Noviembre 2007

Redaccin de docs. tcnicos

32

Procesadores de texto
Pueden mencionarse dos muy populares: Microsoft word Latex

Noviembre 2007

Redaccin de docs. tcnicos

33

Microsoft word
WYSIWYG?: What you see is what you get? WYSIWYWLTG!: What you see is what you would like to get! Fcil de aprender rpidamente Difcil para mantener las referencias cruzadas dentro del documento o a la lista de referencias El manejo de documentos largos es complicado

Noviembre 2007

Redaccin de docs. tcnicos

34

Latex
YCOGWYAGTG!: You can only guess what you are going to get! (ASCII con comandos como el HTML) WCINAW!: Who cares! its 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, ) Difcil de aprender pero es gratis

Noviembre 2007

Redaccin de docs. tcnicos

35

Finalmente
El control de calidad

Control por el autor

El documento debe revisarse antes de ponerlo en circulacin El autor debera volver a leer el documento tratando de olvidar quin lo ha escrito TODOS los defectos de forma deben corregirse en este momento

Noviembre 2007

Redaccin de docs. tcnicos

37

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

Redaccin de docs. tcnicos

38

El supervisor
El supervisor del equipo tambin tendr responsabilidades en el documento final Si se han limado otros defectos, puede concentrarse en hacer comentarios tiles sobre el contenido tcnico Si lo devuelve sin correcciones es que no se lo ha leido! Algunos llegarn a ser supervisores algn da y podran no necesitar estas recomendaciones

Noviembre 2007

Redaccin de docs. tcnicos

39

Resumen y conclusiones (I)

Hay que escribir para transmitir informacin Aunque el lector puede leer, volver a leer, saltar a otra seccin, volver atrs, etc., no hay que presumir que tiene mucho tiempo Un buen documento hay que planearlo

Noviembre 2007

Redaccin de docs. tcnicos

40

Resumen y conclusiones (II)

Hay una forma de escribir aceptada en la comunidad cientfico-tcnica
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

Redaccin de docs. tcnicos

41

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/technicalreport/index.xml

Noviembre 2007

Redaccin de docs. tcnicos

42

Referencias II
Ramn y Cajal, S. Reglas y Consejos Sobre Investigacin Cientfica. Coleccin 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.

Noviembre 2007

Redaccin de docs. tcnicos

43

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

Noviembre 2007

Redaccin de docs. tcnicos

44