Por favor, haz clic aquí para ayudar. David McMurrey pagar por alojamiento web:
¡Dona cualquier pequeña cantidad que puedas!
La redacción técnica en línea seguirá siendo gratuita.
Los documentos técnicos (incluidos manuales, documentos técnicos y guías) tienen diversos diseños según la industria, profesión u organización. Este capítulo te muestra un diseño tradicional. Si estás tomando un curso de redacción técnica, asegúrate de que el diseño presentado en este capítulo sea aceptable. Lo mismo ocurre si estás escribiendo un documento técnico en un contexto científico, empresarial o gubernamental.
Infografía generada por NotebookLM de este capítulo
Nota: Durante años, este libro de texto en línea sobre escritura técnica se refería genéricamente a los informes como prácticamente cualquier cosa que contuviera información técnica. Pero dado que "informe" se refiere a un género específico de documento técnico, se tuvo que hacer el cambio al genérico "techdoc", abreviatura de documento técnico.
Los techdocs (nombre genérico para documentos técnicos) tienen especificaciones al igual que cualquier otro tipo de proyecto. Las especificaciones para techdocs involucran diseño, organización y contenido, formato de títulos y listas, el diseño de los gráficos, y así sucesivamente. La ventaja de una estructura y formato requeridos para los techdocs es que tú o cualquier otra persona pueden esperar que estén diseñados de una manera familiar—sabes qué buscar y dónde buscarlo. Los techdocs usualmente se leen con prisa—las personas tienen prisa por llegar a la información que necesitan, los hechos clave, las conclusiones y otros elementos esenciales. Un formato estándar de techdoc es como un vecindario familiar.
Cuando analices el diseño de un documento técnico, notarás cuán repetitivas son algunas secciones. Esta duplicación se debe a cómo las personas leen documentos técnicos. No leen los documentos técnicos de manera lineal: pueden comenzar con el resumen ejecutivo, saltar de un lado a otro y probablemente no lean cada página. Tu desafío es diseñar documentos técnicos de manera que estos lectores encuentren tus hechos y conclusiones clave, sin importar cuánto del documento técnico lean o en qué orden lo lean.
Asegúrate de ver el ejemplo de docs técnicos.
Los componentes estándar del informe técnico típico se discuten en este capítulo. Las siguientes secciones te guiarán a través de cada uno de estos componentes, señalando las características clave. A medida que leas y uses estas pautas, recuerda que son pautas, no mandamientos. Diferentes empresas, profesiones y organizaciones tienen sus propias pautas variadas para los documentos técnicos—debes adaptar tu práctica a esas así como a las que se presentan aquí.
Mensaje de Transmisión
El mensaje de transmisión es ya sea una carta de presentación (o memo) o un correo electrónico. La carta física (o memo) está ya sea adjunta al exterior del documento técnico con un clip o encuadernada dentro del documento técnico. El correo electrónico contiene un enlace al documento técnico o el documento técnico adjunto. Es una comunicación de usted—el escritor del documento técnico—al destinatario, la persona que solicitó el documento técnico y que quizás incluso le esté pagando por su consulta experta. Esencialmente, dice "Está bien, aquí está el documento técnico que acordamos que completaría para tal fecha. Brevemente, contiene esto y aquello, pero no cubre esto ni aquello. Hágame saber si satisface sus necesidades." El mensaje de transmisión explica el contexto—los eventos que llevaron a la creación del documento técnico. Contiene información sobre el documento técnico que no pertenece al documento técnico.
Ejemplos de una carta de transmisión y un mensaje de transmisión.
En el ejemplo de la carta de envío, observe el formato estándar de carta comercial. Si escribe un documento técnico interno, use el formato de memorando en su lugar; en cualquier caso, el contenido y la organización son los mismos:
Primer párrafo. Cita el nombre del techdoc, poniéndolo en cursiva. También menciona la fecha del acuerdo para escribir el techdoc.
Párrafo medio. Se centra en el propósito del techdoc y proporciona una breve descripción del contenido del techdoc.
Párrafo final. Anima al lector a ponerse en contacto si tiene preguntas, comentarios o inquietudes. Termina con un gesto de buena voluntad, expresando la esperanza de que el lector encuentre el documento técnico satisfactorio.
Al igual que con cualquier otro elemento en un documento técnico, es posible que debas modificar el contenido de este mensaje (o memo) para situaciones específicas. Por ejemplo, podrías querer añadir otro párrafo, enumerando preguntas que te gustaría que los lectores consideraran mientras revisan el documento técnico.
Cubiertas, Página de Título y Etiqueta
Si tu documento técnico tiene más de diez páginas, encuádalo de alguna manera y crea una etiqueta para la portada.
Cubiertas
Las cubiertas le dan a los documentos técnicos un aspecto sólido y profesional, así como protección. Puedes elegir entre muchos tipos de cubiertas. Ten en cuenta estos consejos:
- Totalmente inaceptables son las fundas de plástico claro (o de color) con la funda de plástico en el borde izquierdo. Son como algo salido de un curso de inglés de primer año; además son molestos de usar—los lectores deben esforzarse por mantenerlas abiertas y lidiar con la electricidad estática que generan.
- Marginalmente aceptables son las cubiertas para las cuales perforas agujeros en las páginas, cargas las páginas y doblas los sujetadores. Si usas este tipo, deja un margen extra de media pulgada en el borde izquierdo para que los lectores no tengan que forzar las páginas. Por supuesto, este tipo de cubierta impide que las páginas queden planas: los lectores deben agarrar objetos disponibles o usar varias partes del cuerpo para mantener las páginas pesadas.
- Hasta ahora, las mejores cubiertas son aquellas que permiten que los documentos técnicos queden abiertos por sí mismos (vea la ilustración en la siguiente sección). Qué gran alivio es tener un documento técnico abierto en su regazo o en su escritorio. Este tipo utiliza una espiral de plástico para el encuadernado y papel rígido grueso para las cubiertas. Consulte con su tienda de copias local sobre estos tipos de encuadernaciones; son económicas y añaden profesionalismo a su trabajo. Vea el ejemplo simulado de una encuadernación de espiral de plástico a continuación.
Generalmente, son menos preferibles los cuadernos de hojas sueltas o los carpetas de anillas. Estos son demasiado voluminosos para documentos técnicos cortos, y los agujeros de las páginas tienden a rasgarse. Por supuesto, la carpeta de anillas facilita el cambio de páginas; si así es como se utilizará tu documento técnico, entonces es una buena opción. En el "alto nivel" están las cubiertas demasiado elegantes con su aspecto de imitación de cuero y adornos dorados. Evítalas—manténlo simple, sencillo y funcional.
Página de Título
En su forma más simple, un título de documento técnico es una copia de lo que está en la portada—posiblemente con algunos detalles añadidos.
Echa un vistazo a la página del título. Resumen y Resumen Ejecutivo.
Etiquetas
Asegúrate de idear una etiqueta para la portada de tu documento técnico. Es un paso que algunos escritores de documentos técnicos olvidan. Sin una etiqueta, un documento técnico es anónimo; se ignora.
La mejor manera de crear una etiqueta es usar tu software de procesamiento de texto para diseñar una en una página estándar con un cuadro gráfico alrededor de la información de la etiqueta. Imprímelo, luego ve a una copiadora y haz que se fotocopie directamente en la cubierta del documento técnico.
No hay mucho que poner en la etiqueta: el título del documento técnico, tu nombre, el nombre de tu organización, un número de seguimiento del documento técnico y una fecha. No hay requisitos estándar para la etiqueta, aunque tu empresa u organización debería tener sus propios requisitos. (A continuación se muestra un ejemplo de una etiqueta de documento técnico.)
Carta de transmisión y portada de documento técnico (con etiqueta de portada).
Resumen y Resumen Ejecutivo
La mayoría de los documentos técnicos contienen al menos un resumen—a veces dos, en cuyo caso los resúmenes cumplen diferentes roles. Los resúmenes sintetizan el contenido de un documento técnico, pero los diferentes tipos lo hacen de maneras distintas:
- Resumen descriptivo. Este tipo proporciona una visión general del propósito y contenido del techdoc. En algunos diseños de techdoc, el resumen descriptivo se coloca al final de la página del título, como se muestra a continuación:
Resumen descriptivo. Tradicionalmente, se coloca en la página del título (no en la página de la portada). - Resumen ejecutivo. Otro tipo común es el resumen ejecutivo, que también resume los hechos clave y las conclusiones contenidas en el techdoc. Vea el ejemplo que se muestra a continuación. Es como si hubiera utilizado un marcador amarillo para resaltar las oraciones clave en el techdoc y luego las hubiera extraído todas a una página separada y editadas para facilitar la lectura. Típicamente, los resúmenes ejecutivos son de una décima a una vigésima parte de la longitud de los techdocs de diez a cincuenta páginas. Para techdocs más largos, aquellos de más de cincuenta páginas, el resumen ejecutivo no debe exceder dos páginas. El objetivo del resumen ejecutivo es proporcionar un resumen del techdoc—algo que se puede leer rápidamente.
Si el resumen ejecutivo, la introducción y el mensaje de transmisión te parecen repetitivos, recuerda que los lectores no necesariamente comienzan al principio de un documento técnico y leen página por página hasta el final. Ellos saltan entre secciones: pueden escanear la tabla de contenidos; generalmente hojean el resumen ejecutivo en busca de hechos y conclusiones clave. Pueden leer detenidamente solo una o dos secciones del cuerpo del documento técnico y luego saltarse el resto. Por estas razones, los documentos técnicos están diseñados con cierta duplicación para que los lectores puedan asegurarse de ver la información importante sin importar por dónde se adentren en el documento técnico.
Índice (que viene primero) luego el resumen ejecutivo.
Tabla de Contenidos
Cualquiera que sea el formato de tabla de contenido (TOC) que uses, estos son los estándares comunes:
- Número de página de inicio solamente. Aunque algunos generadores automáticos de TOC muestran el rango de páginas, el estándar es solo el número de la primera página.
- Niveles de encabezados a incluir. Como se muestra en la tabla de contenido arriba, muestra los dos primeros niveles de encabezados a menos que el documento técnico tenga muchos subencabezados. La tabla de contenido debe proporcionar una forma rápida de encontrar información.
- Espaciado y capitalización. Tenga en cuenta cómo los elementos de texto en el TOC arriba están indentados. Los encabezados de primer nivel utilizan mayúsculas; los encabezados de segundo nivel utilizan mayúscula inicial en cada palabra principal; los encabezados de tercer nivel utilizan mayúsculas de estilo oración.
- Espaciado vertical. Observe que las secciones de primer nivel tienen espacio extra arriba y abajo, lo que aumenta la legibilidad.
- Todas las páginas en el techdoc (dentro pero excluyendo las portadas) están numeradas; pero en algunas páginas, los números no se muestran.
- En el diseño contemporáneo, todas las páginas del documento utilizan números arábigos; en el diseño tradicional, todas las páginas antes de la introducción (primera página del cuerpo de la ) utilizan números romanos en minúsculas.
- En páginas especiales, como la página de título y la página uno de la introducción, los números de página no se muestran.
- Los números de página se pueden colocar en una de varias áreas de la página. Por lo general, la mejor y más fácil opción es colocar los números de página en la parte inferior central de la página (recuerda ocultarlos en páginas especiales).
- Si colocas números de página en la parte superior de la página, debes ocultarlos en las aperturas de capítulos o secciones donde haya un encabezado o título en la parte superior de la página.
- ¿Contiene el techdoc (informe) lo siguiente (formateado correctamente) en este orden: mensaje de transmittal; página de título; tabla de contenido; lista de figuras, tablas o ambas; introducción; secciones del cuerpo (capítulos); apéndices (según sea necesario); fuentes de información; contraportada (si es necesario)? Para más detalles, consulte Diseño de Techdoc.
- Aunque puede ser ingenioso y juguetón, ¿el título del documento técnico indica adecuadamente su tema? Para más detalles, consulta Títulos de Techdoc.
- Si la tabla de contenido y la lista de figuras (y tabla) utilizan puntos guía, ¿están los números de página alineados a la derecha? Si la tabla de contenido y la lista de figuras (y tabla) incluyen números de página en el borde derecho de la página, ¿se utilizan puntos guía? Para más detalles, consulte Índices y Lista de Figuras (Tablas).
- ¿La introducción indica adecuadamente el tema, propósito y audiencia prevista del documento técnico? ¿Proporciona una lista de subtópicos a tratar y una indicación del alcance (lo que no se cubre)? Para más detalles, consulte Introducciones.
- ¿Contiene este documento técnico detalles adecuados, especificaciones, ejemplos—lo que sea necesario para explicar las afirmaciones, las generalidades?
- Considerando el tema, el propósito y la audiencia, ¿falta algún contenido vital en este documento técnico? ¿Hay algún contenido innecesario? ¿Hay alguna información en este documento técnico que sea técnicamente incorrecta? ¿Falta alguna información técnica crítica?
- En este documento tecnológico, ¿contiene alguna información claramente tomada de otras fuentes que no esté documentada de ninguna manera?
- ¿Ocurren las citas (referencias a elementos en la lista de fuentes de información) en el cuerpo del documento técnico formateado según el estilo APA, MLA o IEEE modificado? ¿Están los elementos en la lista de fuentes de información formateados según el estilo APA, MLA o IEEE modificado? Para más detalles, véase Documentación: fuentes de información prestadas.
- ¿Todas las tablas y figuras no decorativas incluyen un título descriptivo (leyenda) y fuente (si es necesario)? Para más detalles, consulte Títulos de la tabla.
- ¿Ocurren todas las tablas y figuras no decorativas lo más cerca posible de su texto relevante?
- ¿Ocurren referencias cruzadas brevemente explicativas antes de las tablas y figuras no decorativas? Para más detalles, consulte Referencias cruzadas explicativas.
- ¿Se utiliza un formato estándar de encabezados y subtítulos en el cuerpo del documento técnico? Para más detalles, consulte Encabezados.
- ¿Las secciones principales (capítulos) del documento técnico comienzan en una nueva página en las versiones impresas?
- ¿Se utilizan listas verticales numeradas para elementos de lista en un orden requerido? ¿Se utilizan listas verticales con viñetas para elementos de lista en un orden no requerido? ¿Se utilizan introducciones antes de todas las listas? Para más detalles, consulte Listas verticales.
- ¿Las citas directas están atribuidas y están correctamente puntuadas las atribuciones? ¿Están todas las citas directas, resúmenes y paráfrasis correctamente citados según el estilo APA, MLA o IEEE modificado? Para más detalles, consulte Citas y atribuciones.
- ¿Está el texto del techdoc libre de errores de gramática, uso y puntuación? Para más detalles, consulte Problemas comunes de gramática, uso y ortografía.
- ¿Está el texto del documento técnico libre de palabrería y otros errores de estilo de oración? Para más detalles, consulte Verbosidad, otros problemas de estilo de oración.
- ¿Puede este documento técnico ser entendido por su público objetivo (como se indica en el mensaje de transmisión y en la introducción)? Para más detalles, consulte Análisis de la audiencia, y ver Traduciendo lo técnico.
- IA, para completar tu evaluación de mi documento técnico, asigna una calificación numérica del 100 al 55.
Puntos de líder y números de página alineados a la derecha. Para el índice tradicional que utiliza puntos de líder y números de página alineados a la derecha:
Alineación a la derecha. En este ejemplo, nota que los puntos de líder "conducen" hacia los números de página que están alineados a la derecha.
Puntos de líder y números de página alineados a la derecha.
Este TOC utiliza un estilo de numeración decimal para los números de capítulo y sección, que es común en documentos técnicos. Otros en este libro utilizan el estilo de numeración romana en mayúsculas solo para los capítulos de nivel superior (ver ).
¿Problemas para crear un TOC bien formateado? Ver Crear un índice con apariencia profesional
Comas y números de página. Si no se requiere un formato de líder con puntos y prefieres evitarlo, puedes usar este formato comúnmente aceptado:
|
3. PRINCIPIOS CLAVE DE LA EFICIENCIA ENERGÉTICA, 5
Estrategias de Diseño Pasivo, 6
4. NORMAS Y CERTIFICACIONES, 11Sistemas de Energía Activa, 7 Integración de Energía Renovable, 9
LEED, 11
Energy Star, 12 Desafío del Edificio Vivo, 14 |
Lista de Figuras y Tablas
La lista de figuras tiene muchas de las mismas consideraciones de diseño que la tabla de contenidos. Los lectores utilizan la lista de figuras para encontrar las ilustraciones, diagramas, tablas y gráficos en su documento técnico.
Las complicaciones surgen cuando tienes tanto tablas como figuras. Hablando estrictamente, las figuras son ilustraciones, dibujos, fotografías, gráficos y cuadros. Las tablas son filas y columnas de palabras y números; no se consideran figuras.
Para documentos técnicos más largos que contienen docenas de figuras y tablas, crea listas separadas de figuras y tablas. Colócalas juntas en la misma página si cabe, como se muestra en la ilustración a continuación. Puedes combinar las dos listas bajo el encabezado "Lista de Figuras y Tablas" e identificar los elementos como figura o tabla, como se hace en la ilustración a continuación.
Introducción
Un elemento esencial de cualquier documento técnico es su introducción—asegúrate de tener claro su verdadero propósito y contenido. En un documento técnico, la introducción prepara al lector para leer el cuerpo principal del documento técnico. Ver introducciones para una discusión sobre cómo escribir introducciones.
Vea este ejemplo de una introducción:
Lista de figuras y tablas seguida de la introducción.
Si no hay tablas, hazlo "Lista de Figuras." En un curso de redacción técnica, pregunta a tu instructor si se requiere el estilo de numeración decimal para los encabezados.
Cuerpo del Techdoc
El cuerpo del documento técnico es, por supuesto, el texto principal del documento técnico, las secciones entre la introducción y la conclusión. A continuación se ilustran páginas de muestra.
Encabezados
En todos los techdocs, excepto en los más cortos (dos páginas o menos), utiliza encabezados para marcar los diferentes temas y subtítulos que se cubren. Los encabezados permiten a los lectores hojear tu techdoc y profundizar en esos puntos donde presentas información que desean. Ve encabezados para pautas sobre los encabezados.
Listas con viñetas y numeradas
En el cuerpo de un documento técnico, también utiliza listas con viñetas, numeradas y de dos columnas donde sea apropiado. Las listas ayudan al enfatizar puntos clave, al hacer la información más fácil de seguir y al romper muros sólidos de texto. Ve a listas para pautas sobre listas.
Símbolos, Números y Abreviaturas
Las discusiones técnicas suelen contener muchos símbolos, números y abreviaturas. Recuerda que las reglas para usar números en lugar de palabras son diferentes en el mundo técnico. La antigua regla sobre escribir todos los números por debajo de 10 no siempre se aplica en la documentación técnica. (Ver números vs palabras para pautas.)
Excepto del cuerpo de un documento técnico.
En un curso de escritura técnica, pregunte a su instructor si se requiere el estilo de numeración decimal para los encabezados. Además, puede ser necesario un sistema de documentación diferente—no el IEEE, que es para ingenieros.
Títulos de Gráficas y Figuras
En documentos técnicos, es probable que necesites dibujos, diagramas, tablas y gráficos. Estos no solo transmiten ciertos tipos de información de manera más eficiente, sino que también le dan a tu documento técnico una apariencia adicional de profesionalismo y autoridad. Si nunca has incluido este tipo de gráficos en un documento, hay algunas maneras relativamente fáciles de hacerlo—no necesitas ser un artista gráfico profesional. Para estrategias sobre cómo agregar gráficos a s, consulta gráficos. Para estrategias para agregar tablas a s, consulte mesas.
Referencias cruzadas
Es posible que necesites dirigir a los lectores a información estrechamente relacionada dentro de tus techdos, o a otras fuentes de información que tengan información relevante. Estos se llaman referencias cruzadas. Por ejemplo, pueden dirigir a los lectores desde la discusión de un mecanismo hacia una ilustración del mismo. Pueden dirigir a los lectores a un apéndice donde se proporciona información de fondo sobre un tema (una información de fondo que simplemente no encaja en el texto). Y pueden dirigir a los lectores fuera de tu documento técnico hacia otra información—a artículos, documentos técnicos y libros que contengan información relacionada con la tuya. Al crear referencias cruzadas, sigue estas pautas presentadas en referencias cruzadas.
Conclusiones
Para la mayoría de los documentos técnicos, necesitarás incluir una sección final. Cuando planifiques la sección final de tu documento técnico, piensa en las funciones que puede desempeñar en relación con el resto del documento técnico. Se presentan ideas para secciones finales en conclusiones.
Apéndices
Los apéndices son esas secciones adicionales que siguen a la conclusión. ¿Qué se pone en los apéndices?—cualquier cosa que no encaje cómodamente en la parte principal del documento técnico, pero que no se puede dejar fuera del documento técnico en su totalidad. El apéndice se utiliza comúnmente para grandes tablas de datos, grandes fragmentos de código de muestra, mapas desplegables, información de fondo que es demasiado básica o demasiado avanzada para el cuerpo del documento técnico, o grandes ilustraciones que simplemente no encajan en el cuerpo del . Cualquier cosa que consideres demasiado grande para la parte principal del documento técnico o que creas que sería distraído e interrumpiría el flujo del documento técnico es un buen candidato para un apéndice. Observa que a cada uno se le asigna una letra (A, B, C, y así sucesivamente).
Fuentes de Información
Documentar tus fuentes de información se trata de establecer, mantener y proteger tu credibilidad en la profesión. Debes citar ("documentar") la información prestada sin importar la forma en que la presentes. Ya sea que lo cites directamente, lo parafrasees o lo resumas—sigue siendo información prestada. Ya sea que provenga de un libro, artículo, un diagrama, una tabla, una página web, un folleto de producto, un experto al que entrevistes en persona—sigue siendo información prestada.
Los sistemas de documentación varían según los profesionales y los campos. Los ingenieros utilizan el sistema IEEE, cuyos ejemplos se muestran a lo largo de este capítulo. Otro sistema de documentación comúnmente utilizado es el proporcionado por la Asociación Americana de Psicología (APA). Ver documentación para más detalles.
Numeración de Páginas
El estilo de numeración de páginas utilizado en el diseño tradicional de documentos técnicos difiere del diseño contemporáneo de documentos técnicos, principalmente por el uso de números romanos en minúsculas en el material preliminar (todo lo anterior a la introducción).
Nota: Los documentos técnicos más largos a menudo utilizan el estilo de numeración de páginas conocido como folio por capítulo o doble enumeración (por ejemplo, las páginas del Capítulo 2 serían numeradas 2-1, 2-2, 2-3, y así sucesivamente). De manera similar, las tablas y figuras utilizarían este estilo de numeración. Este estilo facilita el proceso de añadir y eliminar páginas.
Indicaciones de IA para Techdocs
Las listas de verificación, que normalmente no se leen, pueden utilizarse como fuente para los prompts de IA con alguna modificación. Copia lo siguiente, pégalo en un sistema de IA como Google Gemini y ve qué podrías haber pasado por alto.
Nota: Todas las referencias al contenido, formato, estilo de cartas de presentación o sus componentes se pueden encontrar en el libro de texto de escritura técnica en línea.
|
Prompts de IA para Techdocs Cuando quieras que la IA evalúe un proyecto de escritura, preséntate, dile a la IA quién eres y qué deseas. Dale a la IA un punto de referencia para hacer evaluaciones, como un libro de texto en línea. Luego publica lo que deseas que Gemini verifique en su evaluación. Aquí hay un ejemplo: Hola, IA. Soy David McMurrey, un estudiante de ciberseguridad en Austin Community College (Austin, Texas). Solicito que evalúes el siguiente documento técnico utilizando esto. libro de texto en línea y las siguientes preguntas: |
Información relacionada
TOC: Una Herramienta Organizacional Clave para los Lectores
Agradecería tus pensamientos, reacciones y críticas sobre este capítulo: tu respuesta—David McMurrey.
