- Este capítulo, así como el resto del libro de Redacción Técnica, se enfoca en las habilidades de redacción técnica. No se garantiza que el contenido técnico aquí presentado sea exitoso, preciso o esté actualizado.
- Este capítulo fue traducido utilizando OpenAI ChatGPT. Por favor, informe cualquier problema lingüístico a admin@mcmassociates.io.
- El texto en las imágenes de esta página se traducirá lo antes posible.
- Haga clic aquí para ayudar a David McMurrey a pagar el alojamiento web: ¡Done cualquier cantidad! Online Technical Writing seguirá siendo gratuito.
Por favor, haga clic aquí para ayudar. David McMurrey pagar por el 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, white papers y guías) tienen diversos diseños según la industria, la profesión o la organización. Este capítulo le muestra un diseño tradicional. Si está cursando un curso de redacción técnica, asegúrese de que el diseño presentado en este capítulo sea aceptable. Lo mismo ocurre si está 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 redacción técnica se refirió 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, hubo que cambiar a la denominación genérica «techdoc», abreviatura de documento técnico.
Techdocs (nombre genérico para documentos técnicos) tienen especificaciones al igual que cualquier otro tipo de proyecto. Las especificaciones para los techdocs implican el diseño, la organización y el contenido, el formato de los encabezados y las listas, el diseño de los gráficos y así sucesivamente. La ventaja de una estructura y un formato obligatorios para los techdocs es que usted o cualquier otra persona puede esperar que estén diseñados de una manera familiar—usted sabe qué buscar y dónde buscarlo. Los techdocs suelen leerse con prisa—la gente tiene prisa por llegar a la información que necesita, 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, fíjate en lo repetitivas que son algunas secciones. Esta duplicación tiene que ver con la forma en que la gente lee los documentos técnicos. No los leen de principio a fin: pueden empezar por el resumen ejecutivo, saltar de una parte a otra y probablemente no leer cada página. Tu desafío es diseñar los documentos técnicos de manera que estos lectores se encuentren con tus hechos y conclusiones clave, sin importar cuánto del documento técnico lean o en qué orden lo hagan.
Asegúrate de ver el ejemplo de documentación técnica.
Los componentes estándar del informe técnico típico se analizan en este capítulo. Las siguientes secciones lo guían a través de cada uno de estos componentes, señalando las características clave. Mientras lea y utilice estas directrices, recuerde que son directrices, no mandamientos. Diferentes empresas, profesiones y organizaciones tienen sus propias directrices variadas para techdocs—; usted también tendrá que adaptar su práctica a esas, así como a las presentadas aquí.
Mensaje de transmisión
El mensaje de remisión es ya sea una carta de presentación (o memorando) o un correo electrónico. La carta física (o memorando) está 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 redactor del documento técnico—al destinatario, la persona que solicitó el documento técnico y que incluso podría estar pagándole por su consulta experta. Esencialmente, dice: «De acuerdo, aquí está el documento técnico que acordamos que completaría para tal o cual fecha. Brevemente, contiene esto y aquello, pero no cubre esto ni aquello. Hágame saber si cumple con sus necesidades.» El mensaje de remisión explica el contexto—los acontecimientos que dieron lugar al documento técnico. Contiene información sobre el documento técnico que no corresponde incluir en el propio documento técnico.
Ejemplos de una carta de remisión y de un mensaje de remisión.
En el ejemplo de la carta de remisión, observe el formato estándar de carta comercial. Si redacta un documento técnico interno, utilice en su lugar el formato de memorándum; en ambos casos, el contenido y la organización son los mismos:
Primer párrafo. Cita el nombre del documento técnico, poniéndolo en cursiva. También menciona la fecha del acuerdo para redactar el documento técnico.
Párrafo medio. Se centra en el propósito del documento técnico y ofrece una breve visión general de su contenido.
Párrafo final. Anima al lector a ponerse en contacto si tiene preguntas, comentarios o inquietudes. Cierra con un gesto de buena voluntad, expresando la esperanza de que el lector encuentre el documento técnico satisfactorio.
Como con cualquier otro elemento de un documento técnico, es posible que tenga que modificar el contenido de este mensaje (o memorando) para situaciones específicas. Por ejemplo, quizá desee añadir otro párrafo, enumerando preguntas que le gustaría que los lectores consideraran mientras revisan el documento técnico.
Cubiertas, página del título y etiqueta
Si su documento técnico tiene más de diez páginas, debe encuadernarlo de alguna manera y crear una etiqueta para la portada.
Cubiertas
Las cubiertas dan a techdocs un aspecto sólido y profesional, además de protección. Puedes elegir entre muchos tipos de cubiertas. Ten en cuenta estos consejos:
- Totalmente inaceptables son las fundas deslizantes de plástico transparentes (o de color) que tienen la manga de plástico en el borde izquierdo. Estas parecen sacadas de un curso de inglés de primer año; además son muy molestas de usar—los lectores deben esforzarse por mantenerlas abiertas y lidiar con la electricidad estática que generan.
- Son marginalmente aceptables las cubiertas en las que perforas las páginas, insertas las páginas y doblas las patillas de los remaches. Si usas este tipo, deja un margen adicional de media pulgada en el borde izquierdo para que los lectores no tengan que hacer palanca para separar las páginas. Por supuesto, este tipo de cubierta impide que las páginas queden planas: los lectores deben agarrar objetos disponibles o usar diversas partes del cuerpo para mantener las páginas presionadas hacia abajo.
- Con diferencia, las mejores cubiertas son aquellas que permiten que los manuales técnicos permanezcan abiertos por sí mismos (véase la ilustración en la sección siguiente). ¡Qué gran alivio que un manual técnico pueda permanecer abierto en tu regazo o sobre tu escritorio! Este tipo utiliza una espiral de plástico para la encuadernación y cartulina gruesa para las cubiertas. Consulta en tu copistería local sobre este tipo de encuadernaciones; son económicas y realzan el aspecto profesional de tu trabajo. Véase el ejemplo simulado de una encuadernación con espiral de plástico a continuación.
Generalmente son menos preferibles los cuadernos de hojas sueltas o las carpetas de anillas. Estos son demasiado voluminosos para documentos técnicos cortos, y los orificios de las páginas tienden a rasgarse. Por supuesto, la carpeta de anillas facilita cambiar las páginas; si así es como se usará tu documento técnico, entonces es una buena opción. En la "gama alta" están las cubiertas excesivamente elegantes con su aspecto de piel sintética y adornos de color dorado. Evítalas—mantenlo sobrio, sencillo y funcional.
Página del título
En su forma más simple, el título de un documento técnico es una copia de lo que aparece en la portada—posiblemente con algunos detalles añadidos.
Échale 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 redactores de documentación técnica olvidan. Sin una etiqueta, un documento técnico queda anónimo; se ignora.
La mejor manera de crear una etiqueta es usar su software de procesamiento de texto para diseñarla en una página estándar con un cuadro gráfico alrededor de la información de la etiqueta. Imprímala, luego vaya a una copistería y hágala fotocopiar directamente en la cubierta del documento técnico.
En la etiqueta no aparece mucho: el título del documento técnico, su nombre, el nombre de su organización, un número de seguimiento del documento técnico y una fecha. No hay requisitos estándar para la etiqueta, aunque su empresa u organización debería tener sus propios requisitos. (A continuación se muestra un ejemplo de etiqueta de documento técnico.)
Carta de remisión y portada del documento técnico (con etiqueta en la 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 desempeñan roles diferentes. Los resúmenes sintetizan el contenido de un documento técnico, pero los distintos tipos lo hacen de maneras diferentes:
- Resumen descriptivo. Este tipo proporciona una visión general del propósito y el contenido del documento técnico. En algunos diseños de documento técnico, el resumen descriptivo se coloca en la parte inferior 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 portada). - Resumen ejecutivo. Otro tipo común es el resumen ejecutivo, que también resume los hechos clave y las conclusiones contenidas en el documento técnico. Véase el ejemplo que se muestra a continuación. Es como si hubieras usado un resaltador amarillo para marcar las oraciones clave en el documento técnico y luego las hubieras extraído todas a una página aparte y las hubieras editado para facilitar su lectura. Normalmente, los resúmenes ejecutivos tienen entre una décima y una vigésima parte de la extensión de documentos técnicos de diez a cincuenta páginas. Para documentos técnicos más extensos, aquellos de más de cincuenta páginas, el resumen ejecutivo no debe superar las dos páginas. El objetivo del resumen ejecutivo es ofrecer un resumen del documento técnico—algo que pueda leerse rápidamente.
Si el resumen ejecutivo, la introducción y el mensaje de remisión te parecen repetitivos, recuerda que los lectores no necesariamente comienzan por el principio de un documento técnico y leen página por página hasta el final. Suelen saltar de una parte a otra: pueden ojear la tabla de contenidos; normalmente leen por encima 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 omitir el resto. Por estas razones, los documentos técnicos se diseñan con cierta duplicación para que los lectores estén seguros de ver la información importante, sin importar en qué parte del documento la consulten.
Tabla de contenidos (que va primero) y luego el resumen ejecutivo.
Tabla de contenidos
Sea cual sea el formato de la tabla de contenidos (TOC) que utilices, estos son los estándares comunes:
- Solo número de página inicial. Aunque algunos generadores automáticos de la tabla de contenidos muestran el rango de páginas, lo habitual es mostrar solo el número de la primera página.
- Niveles de encabezados a incluir. Como se muestra en la tabla de contenidos anterior, muestre los dos niveles superiores de encabezados a menos que el documento técnico tenga muchos subencabezados. La tabla de contenidos debe proporcionar una forma de localizar la información de un vistazo.
- Espaciado y uso de mayúsculas. Observe cómo los elementos de texto en la tabla de contenido de arriba tienen sangría. Los encabezados de primer nivel usan MAYÚSCULAS; los encabezados de segundo nivel usan mayúscula inicial en cada palabra principal; los encabezados de tercer nivel usan mayúscula al estilo de oración.
- Espaciado vertical. Observe que las secciones de primer nivel tienen espacio adicional por encima y por debajo, lo que aumenta la legibilidad.
- Todas las páginas del documento técnico (en su interior, pero excluyendo las cubiertas delantera y trasera) están numeradas; pero en algunas páginas, los números no aparecen.
- En el diseño contemporáneo, todas las páginas a lo largo del documento usan números arábigos; en el diseño tradicional, todas las páginas antes de la introducción (primera página del cuerpo del ) usan números romanos en minúsculas.
- En páginas especiales, como la página del título y la primera página de la introducción, no se muestran los números de página.
- Los números de página se pueden colocar en una de varias zonas de la página. Por lo general, la mejor y más sencilla opción es colocar los números de página en la parte inferior central de la página (recuerda ocultarlos en las páginas especiales).
- Si coloca números de página en la parte superior de la página, debe ocultarlos en las páginas de apertura de capítulo o sección donde un encabezado o título aparezca en la parte superior de la página.
- ¿Contiene el documento técnico (informe) lo siguiente (formateado correctamente) en este orden: mensaje de remisión; página de título; tabla de contenidos; 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 documentación técnica.
- Si bien puede ser ingenioso y juguetón, ¿indica adecuadamente el título del documento técnico el tema que trata? Para más detalles, consulte Títulos de documentación técnica.
- Si la tabla de contenidos y la lista de figuras (y de tablas) usan puntos de guía, ¿los números de página están alineados a la derecha? Si la tabla de contenidos y la lista de figuras (y de tablas) incluyen números de página en el borde derecho de la página, ¿se usan puntos de guía? Para más detalles, consulte Índices y lista de figuras (tablas).
- ¿La introducción indica adecuadamente el tema, el propósito y el público destinatario del documento técnico? ¿Proporciona una lista de subtemas que se cubrirán 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, ¿faltan contenidos vitales en este documento técnico? ¿Hay contenidos innecesarios? ¿Alguna información en este documento técnico es técnicamente incorrecta? ¿Falta alguna información técnica crítica?
- ¿Contiene este documento técnico alguna información claramente tomada de otra fuente que no esté documentada de ninguna manera?
- ¿Las citas (referencias a elementos en la lista de fuentes de información) aparecen en el cuerpo del documento técnico formateado según APA, MLA o el estilo IEEE modificado? ¿Los elementos de la lista de fuentes de información están formateados según APA, MLA o el estilo IEEE modificado? Para más detalles, consulte Documentación: fuentes de información tomadas prestadas.
- ¿Incluyen todas las tablas y figuras no decorativas un título descriptivo (leyenda) y la fuente (si es necesario)? Para más detalles, consulte Títulos de tablas.
- ¿Se encuentran todas las tablas y las figuras no decorativas lo más cerca posible del texto relevante?
- ¿Aparecen referencias cruzadas explicativas breves antes de las tablas y las figuras no decorativas? Para más detalles, véase Referencias cruzadas explicativas.
- ¿Se utiliza un formato estándar de encabezados y subencabezados 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 usan listas verticales numeradas para los elementos de la lista que deben seguir un orden? ¿Se usan listas verticales con viñetas para los elementos de la lista que no requieren un orden? ¿Se usan frases introductorias antes de todas las listas? Para más detalles, consulte Listas verticales.
- ¿Se atribuyen las citas textuales y están las atribuciones correctamente puntuadas? ¿Están todas las citas textuales, los resúmenes y las paráfrasis correctamente citados de acuerdo con el estilo APA, MLA o el estilo IEEE modificado? Para más detalles, consulte Citas y atribuciones.
- ¿Está el texto del documento técnico 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 verbosidad y de otros errores de estilo en las oraciones? Para más detalles, consulte Verbosidad, otros problemas de estilo de la oración.
- ¿Puede este documento técnico ser entendido por su público objetivo (según se indica en el mensaje de remisión y en la introducción)? Para más detalles, consulte Análisis de audiencia, y ver Traduciendo lo técnico.
- IA, para completar tu evaluación de mi documento técnico, asigna una calificación numérica de 100 a 55).
Puntos guía y números de página alineados a la derecha. Para la tabla de contenidos tradicional que utiliza puntos guía y números de página alineados a la derecha:
Alineación a la derecha. En este ejemplo, observa que los puntos de relleno "conducen" hacia los números de página que están alineados a la derecha.
Puntos de relleno y números de página alineados a la derecha.
Este índice utiliza el estilo de numeración decimal para los números de capítulos y secciones, que es común en la documentación técnica. Otros en este libro usan el estilo de numeración con números romanos en mayúsculas solo para los capítulos de nivel superior (véase ).
¿Problemas para crear una tabla de contenido bien formateada? Vea Crear una tabla de contenidos de aspecto profesional
Comas y números de página. Si no se requiere un formato con puntos de líder y prefiere evitarlo, puede 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ías Renovables, 9
LEED, 11
Energy Star, 12 Desafío del Edificio Vivo, 14 |
Lista de Figuras y Tablas
La lista de figuras comparte muchas de las mismas consideraciones de diseño que la tabla de contenidos. Los lectores usan la lista de figuras para encontrar las ilustraciones, diagramas, tablas y gráficos en tu documento técnico.
Surgen complicaciones cuando se tienen tanto tablas como figuras. Estrictamente hablando, las figuras son ilustraciones, dibujos, fotografías, gráficos y diagramas. Las tablas son filas y columnas de palabras y números; no se consideran figuras.
Para documentos técnicos más extensos que contienen docenas de figuras y tablas cada uno, cree listas separadas de figuras y tablas. Colóquelas juntas en la misma página si caben, como se muestra en la ilustración siguiente. Puede combinar las dos listas bajo el encabezado «Lista de Figuras y Tablas» e identificar los elementos como figura o tabla tal como se hace en la ilustración mencionada.
Introducción
Un elemento esencial de cualquier documento técnico es su introducción—asegúrese de tener claro su propósito real y sus contenidos. En un documento técnico, la introducción prepara al lector para leer el cuerpo principal del documento técnico. Véase 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, ponga 'Lista de figuras'. En un curso de redacción técnica, pregúntele a su instructor si el estilo de numeración decimal para los encabezados es obligatorio.
Cuerpo del documento técnico
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 muestran páginas de ejemplo.
Encabezados
En todos, salvo en los documentos técnicos más breves (dos páginas o menos), utilice encabezados para señalar los diferentes temas y subtemas tratados. Los encabezados permiten a los lectores hojear su documentación técnica y acceder directamente a los puntos en los que usted presenta la información que buscan. Véase encabezados para obtener pautas sobre los encabezados.
Listas con viñetas y numeradas
En el cuerpo de un documento técnico, utilice también listas con viñetas, numeradas y de dos columnas cuando corresponda. Las listas ayudan a enfatizar los puntos clave, a que la información sea más fácil de seguir y a romper los bloques densos de texto. Véase listas para obtener pautas sobre listas.
Símbolos, números y abreviaturas
Las discusiones técnicas por lo general contienen muchos símbolos, números y abreviaturas. Recuerde que las reglas para usar numerales en lugar de palabras son diferentes en el mundo técnico. La antigua regla de escribir todos los números inferiores a 10 no siempre se aplica en la documentación técnica. (Véase números vs palabras para las directrices.)
Excepto del cuerpo de un documento técnico.
En un curso de redacción técnica, pregunte a su instructor si se requiere el estilo de numeración decimal para los encabezados. Además, puede requerirse un sistema de documentación diferente—no el IEEE, que es para ingenieros.
Gráficos y títulos de figuras
En documentos técnicos, probablemente necesitará 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 su documento técnico un aspecto adicional de profesionalismo y autoridad. Si nunca ha incluido este tipo de gráficos en un documento, existen formas relativamente fáciles de hacerlo—no necesita ser un artista gráfico profesional. Para estrategias para agregar gráficos a s, consulte gráficos. Para estrategias para agregar tablas a s, consulte mesas.
Referencias cruzadas
Es posible que necesites señalar a los lectores información estrechamente relacionada dentro de tus techdos, o a otras fuentes de información que tengan información relevante. Estas se llaman referencias cruzadasPor ejemplo, pueden dirigir a los lectores desde la discusión de un mecanismo hacia una ilustración del mismo. Pueden remitir a los lectores a un apéndice donde se proporciona información de fondo sobre un tema (información de fondo que simplemente no cabe en el texto). Y pueden remitir a los lectores fuera de su documento técnico a otra información—a artículos, documentos técnicos y libros que contienen información relacionada con la suya. Cuando cree referencias cruzadas, siga estas pautas presentadas en referencias cruzadas.
Conclusiones
Para la mayoría de los documentos técnicos, necesitarás incluir una sección final. Al planear 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 pueda omitirse por completo del documento técnico. El apéndice se utiliza comúnmente para grandes tablas de datos, grandes fragmentos de código de ejemplo, mapas plegables, antecedentes que son demasiado básicos o demasiado avanzados para el cuerpo del documento técnico, o grandes ilustraciones que simplemente no encajan en el cuerpo del . Cualquier cosa que consideres demasiado extensa para la parte principal del documento técnico o que creas que sería una distracción e interrumpiría el flujo del documento técnico es una buena candidata 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 tomada prestada sin importar la forma o el modo en que la presentes. Ya sea que la cites directamente, la parafrasees o la resumas—sigue siendo información tomada prestada. Ya sea que provenga de un libro, un artículo, un diagrama, una tabla, una página web, un folleto de producto, un experto a quien entrevistes en persona—sigue siendo información tomada prestada.
Los sistemas de documentación varían según los profesionales y los campos. Los ingenieros utilizan el sistema IEEE, ejemplos del cual se muestran a lo largo de este capítulo. Otro sistema de documentación comúnmente utilizado es el proporcionado por la Asociación Estadounidense de Psicología (APA). Véase documentación para más detalles.
Numeración de páginas
El estilo de numeración de páginas utilizado en el diseño de documentación técnica tradicional difiere del diseño de documentación técnica contemporáneo principalmente en que el primero utiliza 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 suelen utilizar 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 se numerarían 2-1, 2-2, 2-3, y así sucesivamente). De manera similar, las tablas y las figuras utilizarían este estilo de numeración. Este estilo facilita el proceso de añadir y eliminar páginas.
Indicaciones de IA para documentación técnica
Las listas de verificación, que por lo general no se leen, pueden usarse como fuente para indicaciones de IA con algunas modificaciones. Copia lo siguiente, pégalo en un sistema de IA como Gemini de Google y observa lo que podrías haber pasado por alto.
Nota: Todas las referencias al contenido, formato y estilo de las cartas de solicitud o de sus componentes se pueden encontrar en el libro de texto en línea de redacción técnica.
|
Prompts de IA para documentación técnica Cuando quieras que la IA evalúe un proyecto de escritura, preséntate, dile a la IA quién eres y qué quieres. Dale a la IA un punto de referencia para hacer evaluaciones, como un libro de texto en línea. Luego publica lo que quieres que Gemini revise en su evaluación. Aquí tienes un ejemplo: Hola, IA. Soy David McMurrey, 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
Tabla de contenidos: Una herramienta organizativa clave para los lectores
Agradecería sus opiniones, reacciones y críticas con respecto a este capítulo: tu respuesta—David McMurrey.
