Cmo Escribir un Documento Tcnico

_____________________________________________________ Enrique Alba

Dpto. Lenguajes y CC.CC. Univ. de Mlaga, ESPAA Mayo 2002

Resumen. La escritura de un documento tcnico es un problema importante para la mayora de investigadores, especialmente al principio de su carrera profesional. En esta nota breve quiero ofrecer algunos de los comentarios y consejos que usualmente doy a mis estudiantes acerca de cmo escribir un documento de aceptable claridad y estructura. El contenido del presente trabajo pondr de manifiesto los tpicos problemas sobre cmo estructurar la informacin, cmo presentar los objetivos o resultados, y algunas guas para seleccionar las palabras adecuadas, grficos y mecanismos diversos para la transmisin de la informacin hasta sus lectores.

1 Introduccin
En este trabajo presentamos algunos comentarios y consejos para estudiantes e investigadores noveles con la intencin de ayudar en la elaboracin de documentos de buena calidad, conteniendo informacin cientfica y orientados a lectores especializados. Cualquiera que se enfrente al problema de escribir un documento suele experimentar una serie de problemas en los siguientes mbitos: 1. Estructura del documento 2. Guas sobre formato 3. Contenidos 4. Facilidad de lectura 5. Edicin y difusin electrnicas Puesto que mi objetivo es dar una ayuda de la manera ms eficiente posible (rpida e inmediatamente) presentar una especie de lista de actividades que deberan tenerse en cuenta antes/durante/despus de haber terminado el documento tcnico. En realidad, no es una nica lista, sino un conjunto de listas cuyo contenido dependen de los principales problemas que se deben resolver segn el perfil del escritor y segn el enfoque que quiere dar a su trabajo.

Este documento se organiza como sigue. La prxima seccin discutir cmo elaborar la estructura de un documento cientfico. La Seccin 3 discutir las guas para darle formato. La Seccin 4 profundiza en el tipo de contenidos imprescindibles que no deben olvidarse en la redaccin final, mientras que la Seccin 5 contiene consejos para mejorar la legibilidad del documento. Finalmente, la Seccin 6 ofrecer una discusin sobre formatos electrnicos (someramente). Terminaremos con algunas conclusiones que ayuden a resumir los contenidos del presente trabajo en la Seccin 7.

2 Estructura del Documento

Al escribir un documento tcnico, intente mantener en su cabeza que la estructura tradicional debera incorporar las siguientes secciones: A. Introduccin, conteniendo: a. el estado actual del arte, b. trabajos relacionados, c. explcita mencin de los objetivos que se pretenden alcanzar, d. ventajas esperadas de su trabajo en relacin a otros existentes, e. mencione explcitamente sus contribuciones contribuciones de este trabajo son ), (Las

f. describa explcitamente la estructura del documento al final de la introduccin (Este trabajo se estructura en 6 secciones. La Seccin 1 ). B. Problemas, discutiendo: a. los problemas reales que espera resolver con su propuesta, b. referencias a artculos, libros u otros documentos con las mismas instancias de problema que est utilizando (o similares), c. explicacin de las dificultades de los problemas elegidos y del inters que estos puedan tener, d. discusin sobre el estado del arte en la solucin de dichos problemas (incluyendo parmetros usados en las referencias que se hagan), e. resumen formal/matemtico no ambiguo describiendo los problemas. C. Tcnicas de Resolucin, haciendo hincapi en: a. la novedad del mtodo o solucin propuesta, b. la explicacin especfica y no ambigua de dicho mtodo (por ejemplo incluyendo pseudo-cdigos con las variables y elementos usados), c. las caractersticas y requisitos ms sobresalientes, de tipo matemtico o formal, de las tcnicas empleadas, d. los parmetros y decisiones ms importantes que le han llevado a seleccionar dichos mtodos o tcnicas, e. cmo pretende resolver el problema usando dichos fantsticos mecanismos, f. los resultados esperados tras la resolucin. 2

D. Experimentos, presentando: a. cuales son los objetivos concretos que espera conseguir con los experimentos, b. qu parmetros, algoritmos e instancias de cada problema abordado pretende considerar (si es posible use tablas resumen), c. las medidas, anlisis estadstico y criterios que pretende utilizar para juzgar los resultados (justifique dicha eleccin frente a otras), d. los pasos que pretende dar para obtener los resultados (y justifique por qu dichos pasos y no otros). E. Resultados, analizando: a. cada resultado por s mismo; aada grficos y tablas, y discuta cada uno por separado, b. grupos de resultados relacionados, usando como criterio bien el problema para distintos mtodos de resolucin o bien la tcnica de resolucin para varios problemas, c. un resumen de los resultados, con informacin clara sobre conclusiones y datos numricos/grficos/tabulados resumidos. F. Conclusiones, incluyendo: a. un resumen muy breve de lo que se ha dicho/hecho en el documento, b. una explicacin simple o informal de los logros y afirmaciones, c. aada algunas referencias (pocas) o conclusiones tcnicas si resulta apropiado, d. al final de esta seccin, aada algunos detalles sobre por dnde pretende o es de inters continuar el trabajo en el futuro, atendiendo al problema, las tcnicas u otra informacin (p. ej. software o URLs). G. Referencias, resaltando: a. los conceptos ms importantes del trabajo, b. referencias a trabajos similares, c. referencias a las tcnicas bsicas usadas y/o resultados, d. referencias al trabajo que est extendiendo (lnea de trabajo), e. cuide de que todas las referencias del final del documento estn usadas en el cuerpo del documento (hayan sido referenciadas), f. las referencias no son bibliografas con informacin general relativa al contenido, sino documentos concretos cuyo contenido se ha usado, g. incluya preferentemente artculos de revista o libros, considere despus los artculos en conferencias y, finalmente, intente evitar las comunicaciones personales o informes tcnicos si es posible. Adems, recuerde aadir un resumen al principio del documento, en donde incluya los objetivos, el trabajo que se pretende describir y una explicacin abreviada de las conclusiones a las que llegar en el documento. Adicionalmente, utilice un ttulo con 3

significado para el documento y la afiliacin completa de los autores (incluyendo direccin postal, email y URL si es posible). Aada tambin algunas palabras clave que permitan identificar el mbito del documento (evitando palabras que no ayuden por s mismas tales como sistema, software, elemento, algoritmo, etc.). Puede que le interese considerar la inclusin de un ndice al principio del documento si es largo; incluso, puede ser de inters aadir un ndice de tablas o figuras para ayudar al lector. Adems, puede que necesite utilizar uno o ms apndices con informacin de inters pero que no sea imprescindible para entender el documento (nomenclatura, manual de usuario, demostraciones tericas, etc.).

3 Guas para el Formato

Independientemente del editor o aspecto que pretenda dar a su documento intente ser consistente consigo mismo durante toda la escritura del documento. Esto es importante. Aqu se resumen algunos consejos: o Si existe algn estilo ya definido para el tipo de documento que pretende elaborar o para la audiencia del documento, entonces consiga dichas instrucciones de estilo y selas! o Intente poner el nombre de las secciones al menos 4 puntos ms grande que el texto normal. Para la jerarqua de sub-secciones, intente disminuir dicho tamao de letra. o No aada punto final (.) al final del nombre de una seccin: no es una frase. o Ponga en maysculas la inicial de cada palabra del ttulo de la seccin, excepto si la palabra es un artculo, preposicin, o partcula de 4 letras o menos. Por ejemplo: Resultados para el Problema de la Asignacin. o Utilice el mismo tamao de punto y fuente para todas las secciones que residan al mismo nivel en la jerarqua de secciones del documento. o Numere todas las secciones, preferiblemente con nmeros arbigos (1, 2, 3 ...). o No deje en el texto lneas hurfanas (es decir, lneas solas aisladas), tanto al final como al principio de una pgina (o columna, si est usando doble columna). o Haga un esfuerzo por no romper prrafos entre dos pginas sucesivas. Analice la pgina completa para descubrir los prrafos susceptibles de resumir: aquellos con una lnea final de pocas palabras (dos o tres). o No aada tabuladores al primer prrafo de una seccin. o Asegrese de aadir tabuladores a cualquier otro prrafo, incluyendo los prrafos que aparecen tras una ecuacin, tabla o figura. o Si est utilizando abreviaturas (Fig., Ec., etc.) intente ser consistente y usarlos siempre, no slo a veces. o Ponga en maysculas la primera letra de las palabras Figura, Tabla, Ecuacin y Seccin, excepto cuando estn en plural, en cuyo caso utilice minsculas. Es decir, use maysculas si est refirindose a una en particular con su nmero asociado, tal como Seccin 3.

o Intente minimizar el uso de letras en negrita y subrayadas en el documento. Si quiere resaltar un texto intente usar letra itlica (o cursiva). o Ponga en tipo de letra courier el texto que directamente pueda encontrarse en el sistema software (si es el caso). Por ejemplo: nombres de ficheros, clases, mtodos u objetos en un programa orientado a objetos, los presudo-cdigos, etc. data.txt, Buffer.put(a), main.cpp, http://www.net, etc. o Centre las figuras y las tablas en la pgina (cuando sea apropiado). o Aada nmeros de referencia para las ecuaciones. o Si no dispone de un generador de referencias automtico no utilice nmeros para las referencias (tales como [1] o [2]), porque si modifica una sola referencia tendr que cambiarlas todas! Intente usar como referencia el apellido del autor y el ao ([Alba02]) o las iniciales de los autores si hay ms de dos ([ACNT02]). Si la referencia tiene dos autores elija el mecanismo que ms le guste, pero selo consistentemente en el documento.

4 Contenidos
Intente adherirse a los siguientes consejos en relacin al contenido de su documento: o No olvide referenciar explcitamente cada figura/tabla/ecuacin en el texto. o Compruebe que su documento no repite con frecuencia una misma palabra. En Informtica, esto suele ocurrir con sistema, estudio, programa, problema, etc. o Compruebe que est usando consistentemente (siempre igual) el uso del guin - entre dos palabras, y tambin las may/min para los nombres propios. o No utilice palabras sin contenido cientfico tales como bueno o malo. o Ponga una referencia a cada trmino nuevo que aada el texto, y hgalo nicamente la primera vez que se menciona. Cuide de referenciar el trabajo original donde se propuso el trmino, no una referencia que tenga a mano y que hable tambin de dicho tema. o Defina siempre los acrnimos que necesite la primera vez que aparece la frase o explicacin, ponga el acrnimo entre parntesis, y selo a partir de ese momento siempre que sea posible. o No hable de algo que antes no se ha explicado o referenciado en el documento. o Analice las secciones para ver si es posible crear sub-secciones. No use una exposicin continuada en la misma seccin si claramente son dos aspectos diferenciables. o Lea secuencialmente nicamente los nombres de las secciones, desde la introduccin a las conclusiones, con la intencin de detectar problemas de contenido o fluidez de lectura. o Piense en la completitud del documento: hay algo de lo que se est hablando que no est explicado o referenciado en el artculo? o Piense en la correccin del contenido: hay algo incomprensible o incorrecto que deba ser aclarado?

5 Facilidad de Lectura
D una pasada de lectura al documento para chequear los siguientes aspectos: o Compruebe que las frases no sean ms largas de dos o tres lneas. Si existe este tipo de frases es probable que pueda romperlas en otras ms pequeas y legibles. o Compruebe que las figuras/tablas/ecuaciones estn situadas en los lugares correctos del documento, tan cerca como sea posible del lugar donde se las referencia y discute. o Evite situar una figura/tabla/ecuacin de una seccin tras haberla cerrado para empezar otra nueva. o Compruebe que los grficos tienen tamaos legibles para el texto (ttulo, valores, etiquetas de los ejes) y el grosor y tipo de las lneas. Nunca olvide incluir un ttulo para un grfico, los valores de los ejes y una etiqueta explicativa para cada eje. Asegrese que el ttulo es corto y significativo para el contenido (no utilice frases para esto). o Evite el uso de demasiadas lneas internas a las tablas que puedan dificultar su lectura. Puede conseguirse el mismo efecto por la alineacin de filas o columnas. o Siempre que sea posible, incluya grficos y dibujos que expliquen el contenido, el sistema, algoritmos o solucin al problema. Esto ayuda mucho al lector. o Intente alternar entre frases en activa y pasiva, y no abuse de ninguna de ellas.

6 Edicin y Difusin Electrnicas

Pinselo dos veces antes de utilizar un entorno de edicin concreto para el documento. El documento podra ser reutilizado en el futuro (y seguro que lo ser). Piense en las dificultades para reutilizar cada apartado segn la herramienta de edicin. Hoy en da, la mayora de personas utilizan Microsoft Word o Latex. No pretendo comparar ambas, ya que es seguro que las dos tienen ventajas relativas y las dos tienen desventajas. Si se utiliza Word es preferible definir estilos y usar plantillas para el documento, o de otra manera no ser capaz de mantener el contenido y el formato en el futuro. Si se utiliza Latex intente no abusar de las etiquetas no estndares o de muchos paquetes, y tenga siempre a mano un buen editor grfico para generar figuras eps de calidad. En cualquier caso, utilice formatos predefinidos, y evite caractersticas avanzadas que ligaran para siempre el documento al procesador o S.O. usado. Los documentos en pdf son la va que la gente suele preferir debido a su calidad, el pequeo tamao de los ficheros y las capacidades de bsqueda de algunos motores de bsqueda modernos en este formato. Normalmente, los ficheros postscript son mucho ms grandes y necesitan ser comprimidos con Winzip, gzip o similares. Dedique un tiempo a comprobar cmo queda el documento si se exporta a formato html. Volcar el contenido en pginas web puede ser de utilidad.

7 Conclusiones
Esta nota corta pretende servir de documento base para guiar a estudiantes e investigadores noveles en la escritura y transmisin de su trabajo a otras personas. El documento es corto intencionadamente para que sea rpido de leer y anime a ser utilizado. Esto necesariamente supone evitar explicaciones profusas de por qu se hacen los consejos. Las recomendaciones generales ms importantes son mantener la coherencia a lo largo del documento (en contenido y forma), y siempre evaluar la completitud y correccin de la informacin que se ha incluido al escribirlo.