Cómo Escribir un Documento Técnico

Transcripción

1 Cóm Escribir un Dcument Técnic Enrique Alba Dpt. Lenguajes y CC.CC. Univ. de Málaga, ESPAÑA May 2002 Resumen. La escritura de un dcument técnic es un prblema imprtante para la mayría de investigadres, especialmente al principi de su carrera prfesinal. En esta nta breve quier frecer alguns de ls cmentaris y cnsejs que usualmente dy a mis estudiantes acerca de cóm escribir un dcument de aceptable claridad y estructura. El cntenid del presente trabaj pndrá de manifiest ls típics prblemas sbre cóm estructurar la infrmación, cóm presentar ls bjetivs resultads, y algunas guías para seleccinar las palabras adecuadas, gráfics y mecanisms diverss para la transmisión de la infrmación hasta sus lectres. 1 Intrducción En este trabaj presentams alguns cmentaris y cnsejs para estudiantes e investigadres nveles cn la intención de ayudar en la elabración de dcuments de buena calidad, cnteniend infrmación científica y rientads a lectres especializads. Cualquiera que se enfrente al prblema de escribir un dcument suele experimentar una serie de prblemas en ls siguientes ámbits: 1. Estructura del dcument 2. Guías sbre frmat 3. Cntenids 4. Facilidad de lectura 5. Edición y difusión electrónicas Puest que mi bjetiv es dar una ayuda de la manera más eficiente psible (rápida e inmediatamente) presentaré una especie de lista de actividades que deberían tenerse en cuenta antes/durante/después de haber terminad el dcument técnic. En realidad, n es una única lista, sin un cnjunt de listas cuy cntenid dependen de ls principales prblemas que se deben reslver según el perfil del escritr y según el enfque que quiere dar a su trabaj. 1

2 Este dcument se rganiza cm sigue. La próxima sección discutirá cóm elabrar la estructura de un dcument científic. La Sección 3 discutirá las guías para darle frmat. La Sección 4 prfundiza en el tip de cntenids imprescindibles que n deben lvidarse en la redacción final, mientras que la Sección 5 cntiene cnsejs para mejrar la legibilidad del dcument. Finalmente, la Sección 6 frecerá una discusión sbre frmats electrónics (smeramente). Terminarems cn algunas cnclusines que ayuden a resumir ls cntenids del presente trabaj en la Sección 7. 2 Estructura del Dcument Al escribir un dcument técnic, intente mantener en su cabeza que la estructura tradicinal debería incrprar las siguientes seccines: A. Intrducción, cnteniend: a. el estad actual del arte, b. trabajs relacinads, c. explícita mención de ls bjetivs que se pretenden alcanzar, d. ventajas esperadas de su trabaj en relación a trs existentes, e. mencine explícitamente sus cntribucines ( Las cntribucines de este trabaj sn ), f. describa explícitamente la estructura del dcument al final de la intrducción ( Este trabaj se estructura en 6 seccines. La Sección 1 ). B. Prblemas, discutiend: a. ls prblemas reales que espera reslver cn su prpuesta, b. referencias a artículs, librs u trs dcuments cn las mismas instancias de prblema que está utilizand ( similares), c. explicación de las dificultades de ls prblemas elegids y del interés que ests puedan tener, d. discusión sbre el estad del arte en la slución de dichs prblemas (incluyend parámetrs usads en las referencias que se hagan), e. resumen frmal/matemátic n ambigu describiend ls prblemas. C. Técnicas de Reslución, haciend hincapié en: a. la nvedad del métd slución prpuesta, b. la explicación específica y n ambigua de dich métd (pr ejempl incluyend pseud-códigs cn las variables y elements usads), c. las características y requisits más sbresalientes, de tip matemátic frmal, de las técnicas empleadas, d. ls parámetrs y decisines más imprtantes que le han llevad a seleccinar dichs métds técnicas, e. cóm pretende reslver el prblema usand dichs fantástics mecanisms, f. ls resultads esperads tras la reslución. 2

3 D. Experiments, presentand: a. cuales sn ls bjetivs cncrets que espera cnseguir cn ls experiments, b. qué parámetrs, algritms e instancias de cada prblema abrdad pretende cnsiderar (si es psible use tablas resumen), c. las medidas, análisis estadístic y criteris que pretende utilizar para juzgar ls resultads (justifique dicha elección frente a tras), d. ls pass que pretende dar para btener ls resultads (y justifique pr qué dichs pass y n trs). E. Resultads, analizand: a. cada resultad pr sí mism; añada gráfics y tablas, y discuta cada un pr separad, b. grups de resultads relacinads, usand cm criteri bien el prblema para distints métds de reslución bien la técnica de reslución para varis prblemas, c. un resumen de ls resultads, cn infrmación clara sbre cnclusines y dats numérics/gráfics/tabulads resumids. F. Cnclusines, incluyend: a. un resumen muy breve de l que se ha dich/hech en el dcument, b. una explicación simple infrmal de ls lgrs y afirmacines, c. añada algunas referencias (pcas) cnclusines técnicas si resulta aprpiad, d. al final de esta sección, añada alguns detalles sbre pr dónde pretende es de interés cntinuar el trabaj en el futur, atendiend al prblema, las técnicas u tra infrmación (p. ej. sftware URL s). G. Referencias, resaltand: a. ls cncepts más imprtantes del trabaj, b. referencias a trabajs similares, c. referencias a las técnicas básicas usadas y/ resultads, d. referencias al trabaj que está extendiend (línea de trabaj), e. cuide de que tdas las referencias del final del dcument estén usadas en el cuerp del dcument (hayan sid referenciadas), f. las referencias n sn bibligrafías cn infrmación general relativa al cntenid, sin dcuments cncrets cuy cntenid se ha usad, g. incluya preferentemente artículs de revista librs, cnsidere después ls artículs en cnferencias y, finalmente, intente evitar las cmunicacines persnales infrmes técnics si es psible. Además, recuerde añadir un resumen al principi del dcument, en dnde incluya ls bjetivs, el trabaj que se pretende describir y una explicación abreviada de las cnclusines a las que llegará en el dcument. Adicinalmente, utilice un títul cn 3

4 significad para el dcument y la afiliación cmpleta de ls autres (incluyend dirección pstal, y URL si es psible). Añada también algunas palabras clave que permitan identificar el ámbit del dcument (evitand palabras que n ayuden pr sí mismas tales cm sistema, sftware, element, algritm, etc.). Puede que le interese cnsiderar la inclusión de un índice al principi del dcument si es larg; inclus, puede ser de interés añadir un índice de tablas figuras para ayudar al lectr. Además, puede que necesite utilizar un más apéndices cn infrmación de interés per que n sea imprescindible para entender el dcument (nmenclatura, manual de usuari, demstracines teóricas, etc.). 3 Guías para el Frmat Independientemente del editr aspect que pretenda dar a su dcument intente ser cnsistente cnsig mism durante tda la escritura del dcument. Est es imprtante. Aquí se resumen alguns cnsejs: Si existe algún estil ya definid para el tip de dcument que pretende elabrar para la audiencia del dcument, entnces cnsiga dichas instruccines de estil y úselas! Intente pner el nmbre de las seccines al mens 4 punts más grande que el text nrmal. Para la jerarquía de sub-seccines, intente disminuir dich tamañ de letra. N añada punt final (. ) al final del nmbre de una sección: n es una frase. Pnga en mayúsculas la inicial de cada palabra del títul de la sección, except si la palabra es un artícul, prepsición, partícula de 4 letras mens. Pr ejempl: Resultads para el Prblema de la Asignación. Utilice el mism tamañ de punt y fuente para tdas las seccines que residan al mism nivel en la jerarquía de seccines del dcument. Numere tdas las seccines, preferiblemente cn númers arábigs (1, 2, 3...). N deje en el text líneas huérfanas (es decir, líneas slas aisladas), tant al final cm al principi de una página ( clumna, si está usand dble clumna). Haga un esfuerz pr n rmper párrafs entre ds páginas sucesivas. Analice la página cmpleta para descubrir ls párrafs susceptibles de resumir: aquells cn una línea final de pcas palabras (ds tres). N añada tabuladres al primer párraf de una sección. Asegúrese de añadir tabuladres a cualquier tr párraf, incluyend ls párrafs que aparecen tras una ecuación, tabla figura. Si está utilizand abreviaturas ( Fig., Ec., etc.) intente ser cnsistente y usarls siempre, n sól a veces. Pnga en mayúsculas la primera letra de las palabras Figura, Tabla, Ecuación y Sección, except cuand estén en plural, en cuy cas utilice minúsculas. Es decir, use mayúsculas si está refiriéndse a una en particular cn su númer asciad, tal cm Sección 3. 4

5 Intente minimizar el us de letras en negrita y subrayadas en el dcument. Si quiere resaltar un text intente usar letra itálica ( cursiva). Pnga en tip de letra curier el text que directamente pueda encntrarse en el sistema sftware (si es el cas). Pr ejempl: nmbres de fichers, clases, métds u bjets en un prgrama rientad a bjets, ls presud-códigs, etc. data.txt, Buffer.put(a), main.cpp, etc. Centre las figuras y las tablas en la página (cuand sea aprpiad). Añada númers de referencia para las ecuacines. Si n dispne de un generadr de referencias autmátic n utilice númers para las referencias (tales cm [1] [2]), prque si mdifica una sla referencia tendrá que cambiarlas tdas! Intente usar cm referencia el apellid del autr y el añ ([Alba02]) las iniciales de ls autres si hay más de ds ([ACNT02]). Si la referencia tiene ds autres elija el mecanism que más le guste, per úsel cnsistentemente en el dcument. 4 Cntenids Intente adherirse a ls siguientes cnsejs en relación al cntenid de su dcument: N lvide referenciar explícitamente cada figura/tabla/ecuación en el text. Cmpruebe que su dcument n repite cn frecuencia una misma palabra. En Infrmática, est suele currir cn sistema, estudi, prgrama, prblema, etc. Cmpruebe que está usand cnsistentemente (siempre igual) el us del guión - entre ds palabras, y también las may/min para ls nmbres prpis. N utilice palabras sin cntenid científic tales cm buen mal. Pnga una referencia a cada términ nuev que añada el text, y hágal únicamente la primera vez que se mencina. Cuide de referenciar el trabaj riginal dnde se prpus el términ, n una referencia que tenga a man y que hable también de dich tema. Defina siempre ls acrónims que necesite la primera vez que aparece la frase explicación, pnga el acrónim entre paréntesis, y úsel a partir de ese mment siempre que sea psible. N hable de alg que antes n se ha explicad referenciad en el dcument. Analice las seccines para ver si es psible crear sub-seccines. N use una expsición cntinuada en la misma sección si claramente sn ds aspects diferenciables. Lea secuencialmente únicamente ls nmbres de las seccines, desde la intrducción a las cnclusines, cn la intención de detectar prblemas de cntenid fluidez de lectura. Piense en la cmpletitud del dcument: hay alg de l que se está habland que n está explicad referenciad en el artícul? Piense en la crrección del cntenid: hay alg incmprensible incrrect que deba ser aclarad? 5

6 5 Facilidad de Lectura Dé una pasada de lectura al dcument para chequear ls siguientes aspects: Cmpruebe que las frases n sean más largas de ds tres líneas. Si existe este tip de frases es prbable que pueda rmperlas en tras más pequeñas y legibles. Cmpruebe que las figuras/tablas/ecuacines están situadas en ls lugares crrects del dcument, tan cerca cm sea psible del lugar dnde se las referencia y discute. Evite situar una figura/tabla/ecuación de una sección tras haberla cerrad para empezar tra nueva. Cmpruebe que ls gráfics tienen tamañs legibles para el text (títul, valres, etiquetas de ls ejes) y el grsr y tip de las líneas. Nunca lvide incluir un títul para un gráfic, ls valres de ls ejes y una etiqueta explicativa para cada eje. Asegúrese que el títul es crt y significativ para el cntenid (n utilice frases para est). Evite el us de demasiadas líneas internas a las tablas que puedan dificultar su lectura. Puede cnseguirse el mism efect pr la alineación de filas clumnas. Siempre que sea psible, incluya gráfics y dibujs que expliquen el cntenid, el sistema, algritms slución al prblema. Est ayuda much al lectr. Intente alternar entre frases en activa y pasiva, y n abuse de ninguna de ellas. 6 Edición y Difusión Electrónicas Piénsel ds veces antes de utilizar un entrn de edición cncret para el dcument. El dcument pdría ser reutilizad en el futur (y segur que l será). Piense en las dificultades para reutilizar cada apartad según la herramienta de edición. Hy en día, la mayría de persnas utilizan Micrsft Wrd Latex. N pretend cmparar ambas, ya que es segur que las ds tienen ventajas relativas y las ds tienen desventajas. Si se utiliza Wrd es preferible definir estils y usar plantillas para el dcument, de tra manera n será capaz de mantener el cntenid y el frmat en el futur. Si se utiliza Latex intente n abusar de las etiquetas n estándares de muchs paquetes, y tenga siempre a man un buen editr gráfic para generar figuras eps de calidad. En cualquier cas, utilice frmats predefinids, y evite características avanzadas que ligarían para siempre el dcument al prcesadr S.O. usad. Ls dcuments en pdf sn la vía que la gente suele preferir debid a su calidad, el pequeñ tamañ de ls fichers y las capacidades de búsqueda de alguns mtres de búsqueda mderns en este frmat. Nrmalmente, ls fichers pstscript sn much más grandes y necesitan ser cmprimids cn Winzip, gzip similares. Dedique un tiemp a cmprbar cóm queda el dcument si se exprta a frmat html. Vlcar el cntenid en páginas web puede ser de utilidad. 6

7 7 Cnclusines Esta nta crta pretende servir de dcument base para guiar a estudiantes e investigadres nveles en la escritura y transmisión de su trabaj a tras persnas. El dcument es crt intencinadamente para que sea rápid de leer y anime a ser utilizad. Est necesariamente supne evitar explicacines prfusas de pr qué se hacen ls cnsejs. Las recmendacines generales más imprtantes sn mantener la cherencia a l larg del dcument (en cntenid y frma), y siempre evaluar la cmpletitud y crrección de la infrmación que se ha incluid al escribirl. 7