Introducción al Technical Writing

1

¿Qué es Technical Writing? Lleva tu documentación al siguiente nivel

2

Habilidades para convertirte en Technical Writer

3

¿Conoces a tu público? Escribe específicamente para tu audiencia

4

Cómo entrevistar equipos de programación para recolectar información técnica

Estructura gramatical

5

Un repaso por la gramática básica

6

Voz activa vs. voz pasiva: estándares y estructura de una oración

7

Uso correcto de acrónimos y abreviaturas para explicar términos desconocidos

Técnicas de escritura fundamentales para documentos técnicos

8

Sigue las reglas de George Orwell para escribir con claridad

9

Uso correcto de listas y tablas para ordenar información

10

Tipos de párrafos y paso a paso para estructurarlos

Conceptos básicos de programación e ingeniería de software

11

¿Qué es programación? Evolución de la documentación y technical writing

12

Lenguajes de programación, tipos de datos y estructura de documentos HTML

Estándares de documentación de código

13

Cómo documentar una función de código

14

Buenas prácticas de legibilidad para código y comentarios

Organización y revisión de tu documentación

15

Organiza y define el alcance de tus documentos

16

Utiliza Markdown en documentos técnicos

17

Guía para revisar documentación en equipo de manera efectiva

18

Cómo organizar documentos largos

Diseño de documentos

19

Crea ilustraciones instructivas

Conclusiones

20

Siguientes pasos para convertirte en Technical Writer profesional

Voz activa vs. voz pasiva: estándares y estructura de una oración

6/20

Lectura

La voz verbal es todo un fenómeno. Sirve para marcar la relación que tiene el sujeto con el verbo. El verbo tiene dos voces: voz activa y voz pasiva. Aunque en español es un poco difícil de comprender, la usamos de manera inconsciente en nuestro día a día, así que quizás ahora que leas este capítulo prestes atención a la estructura que das a tus oraciones, ya sea al hablar o escribir.

Definición de voz activa y voz pasiva 🤓

La voz activa es el estándar para el technical writing. La mayor parte de las frases en la escritura técnica están en voz activa debido a que es más corta e interesante de leer. Además, la voz activa muestra claramente al sujeto en una situación, cuando leemos en esta voz gramatical sabemos quién hace qué y a quién.

Por otro lado, está la voz pasiva. Como su nombre lo indica, el sujeto aparece como paciente. Se hace énfasis en un estado o en una acción.

Ejemplos de voz activa y voz pasiva 💥

  • Voz activa: Ellos hablan el idioma francés.
  • Voz pasiva: El idioma francés es hablado por ellos.

La voz activa nos muestra que los actores son “Ellos”, en cambio, con la voz pasiva “ellos” quedan opacados.

  • Voz activa: El estudiante edita el archivo.
  • Voz pasiva: El archivo es editado por el estudiante.

De nuevo, la voz activa nos muestra que el actor es “El estudiante” y en la voz pasiva “el estudiante” queda sin mucha importancia.

Las frases que tienen la palabra “por” son casi siempre pasivas y sus verbos terminan en tiempo pasado participio: “hablado”, “editado”, etcétera. No obstante, si tienes una frase pasiva, la puedes convertir en activa. Solo pones al actor de tu oración al inicio y listo.

Estructura para oraciones cortas 👷‍♀️

En resumen, podríamos estructurar las oraciones cortas de la siguiente manera:

  • Voz activa = sujeto + verbo + objetivo.
  • Voz pasiva = objetivo + verbo + sujeto.

Identifica verbos pasivos 🕵️‍♀️

Puedes identificar fácilmente los verbos pasivos, normalmente siguen la siguiente fórmula:

  • Verbo pasivo = verbo ser + verbo en participio.

Ejemplos:

  • Fue seleccionado.
  • Es reconocido.
  • Es programado.
  • Es llamado.
  • Fue dichoso.

Los verbos en participio normalmente terminan en -ado y en -ido. Algunos ejemplos son:

  • Leído
  • Encontrado
  • Huido
  • Olvidado
  • Recomendado

Es importante mencionar que existen algunos verbos en participio que son irregulares, es decir, que no necesariamente terminan en -ado o en -ido. Por ejemplo:

  • Propuesto
  • Roto
  • Expuesto
  • Hecho

Si la frase contiene un sujeto, normalmente la preposición “por” sigue al verbo pasivo. Esta preposición suele ser una ayuda para detectar la voz pasiva. Ejemplos:

  • Fue seleccionado por el jurado.
  • Es reconocido por la universidad.
  • Es programado por los estudiantes.

Los verbos imperativos son voz activa 😌

Un verbo en modo imperativo se usa para dar una indicación, orden o consejo. Cuando hacemos listas (tema que veremos en un futuro) lo recomendado es que las frases inicien con un verbo en modo imperativo. Por ejemplo:

  • Pulsa sobre «Nuevo» para crear una partición nueva.
  • Elige el tamaño de la nueva partición.
  • Reinicia el sistema varias veces.

Estas frases que usan al inicio un verbo en modo imperativo están en voz activa, aunque no mencionan directamente a un sujeto, ya que el sujeto implícito eres tú.

¡Practiquemos ejemplos complejos de voz activa y pasiva! 💪

Este tema es complejo y traté de hacerlo lo más digerible para ti. Las frases que te compartí en los ejemplos anteriores son sencillos y con un solo verbo. Adicional a lo explicado, tengo que compartirte que a lo largo de tu profesión como technical writer te encontrarás con frases que contienen más de un verbo. Te comparto unos últimos ejemplos.

En esta oración todo es voz pasiva:

  • El bloque de su código es ejecutado en el navegador y como un comentario es insertado el bloque de su código.

Esta es la misma oración convertida parcialmente a voz activa:

  • El navegador ejecuta el bloque de su código y como un comentario el bloque de su código es insertado.

Misma oración convertida en su totalidad a voz activa:

  • El navegador ejecuta el bloque de su código y se inserta como un comentario el bloque de su código.

La voz activa es mejor que la voz pasiva 🔥

Te recomiendo que uses con mayor frecuencia la voz activa que la voz pasiva. Cuando leemos nuestra mente tiende a convertir la voz pasiva en activa. Si usamos la voz activa, ahorramos tiempo a nuestro lector en procesar la información.

La voz pasiva da muchas vueltas a algo sencillo. Sí, informa la acción, pero de manera indirecta y opacan al sujeto por completo. La voz activa es mejor que la voz pasiva porque te ayuda a ser corto, claro y directo.

¿Puedes cambiar el tipo de voz en una oración? 👊

Como reto de esta clase reescribe estas oraciones de voz pasiva a voz activa:

  • Varios recursos son descritos en los archivos del directorio values/.
  • Un único recurso es definido en cada campo secundario del elemento .
  • Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.

¡Deja tu solución a los ejercicios en la sección de comentarios! En el próximo módulo estudiaremos buenas y malas prácticas para que nuestros escritos sean claros y bien estructurados.

Aportes 64

Preguntas 0

Ordenar por:

¿Quieres ver más aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesión.

  • Los archivos del directorio values/ describen varios recursos.
  • Cada campo secundario del elemento define un único recurso.
  • Los subdirectorios definidos guardan tus recursos predeterminados.

Voz pasiva

  • Varios recursos son descritos en los archivos del directorio values/.
  • Un único recurso es definido en cada campo secundario del elemento <resources>.
  • Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.

Voz activa

  • Los archivos del directorio values/ describen varios recursos.
  • En cada campo decundario del elemento <resources> se define un único recurso.
  • Los subdirectorios definidos guardaron tus recursos predeterminados.
  • (Pasiva) Varios recursos son descritos en los archivos del directorio values/. -> (Activa) Los archivos del directorio values/ describen varios recursos.

  • (Pasiva) Un único recurso es definido en cada campo secundario del elemento <resources>. -> (Activa) El elemento <resources> define en cada campo secundario un único recurso

  • (Pasiva) Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos. -> (Activa) En los subdirectorios definidos han sido guardados tus recursos predeterminados

📌 Lo que considero más importante:
.
La voz activa es el estándar para el technical writing. La mayor parte de las frases en la escritura técnica están en voz activa debido a que es más corta e interesante de leer. Además, la voz activa muestra claramente al sujeto en una situación, cuando leemos en esta voz gramatical sabemos quién hace qué y a quién.
.
Cuando hacemos listas lo recomendado es que las frases inicien con un verbo en modo imperativo. Por ejemplo:

  • Pulsa sobre «Nuevo» para crear una partición nueva.
  • Elige el tamaño de la nueva partición.
  • Reinicia el sistema varias veces.
  • En los archivos del directorio values/ se describen varios recursos.
  • En cada campo secundario del elemento <resources> se define un único recurso.
  • En los subdirectorios definidos se guardan tus recursos predeterminados.

Aquí está mi solución al reto

Primera oración:

Los archivos del directorio values/ describen varios recursos.


Segunda oración:

Cada campo secundario del elemento define un único recurso.


Tercera oración:

Los recursos que han sido guardados en los subdirectorios definidos son tus recursos predeterminados.

¡Hola! A continuación el desarrollo del reto:

Varios recursos son descritos en los archivos del directorio values/.: Los archivos del directorio values/ describen varios recursos.

Un único recurso es definido en cada campo secundario del elemento.: En cada campo secundario del elemento se define un único recurso.

Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.: Tus recursos predeterminados se guardan en los subdirectorios definidos (no estoy seguro de ésta, aunque la idea es la misma 😄).

¡Saludos!

Los archivos del directorio values/ describen varios recursos.
Cada campo secundario del elemento define un único recurso.
Los recursos guardados en los subdirectorios definidos son recursos predeterminados.

Varios recursos son descritos en los archivos del directorio values/.
En los archivos del directorio values/. se describen varios recursos

Un único recurso es definido en cada campo secundario del elemento .
Para cada campo secundario del elemento se define un único recurso

Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.
En los subdirectorios definidos se guardan tus recursos predeterminados

  1. En los archivos del directorio values/ se describen varios recursos.
  2. En cada campo secundario del elemento se define un único recurso.
  3. Los recursos que han sido guardados en los subdirectorios definidos son tus recursos determinados.
  • Los archivos del directorio son descritos en varios recursos
     

  • Un único recurso es definido en cada campo secundario del elemento.
    En cada campo secundario del elemento es definido un único recurso.
     

  • En los subdirectorios definidos han sido guardados tus recursos predeterminados.

  • Los archivos del directorio son descritos en varios recursos.

  • Un único recurso es definido en cada campo secundario del elemento.

  • En cada campo secundario del elemento es definido un único recurso.

  • En los subdirectorios definidos han sido guardados tus recursos predeterminados.

  • En los archivos del directorio están descritos varios recursos

  • En cada campo secundario del elemento hay un único recurso definido

  • En los subdirectorios definidos se guardan tus recursos predeterminados

  • Varios recursos son descritos en los archivos del directorio values/.
  • En los archivos dell directorio values/ describe varios recursos.
  • Un único recurso es definido en cada campo secundario del elemento .
  • En cada campo secundario del elemento son definidos un único recurso.
  • Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.
  • En los subdirectorios definidos tus recursos predeterminados son guardados.

En los archivos del directorio values/ están descritos varios recursos.
En cada campo secundario del elemento se define un único recurso.
En los subdirectorios definidos se han guardado tus recursos predeterminados.

  • En los archivos del directorio values/ se describen varios recursos.
  • En cada campo secundario del elemento se define un único recurso
  • En los subdirectorios definidos se guardan tus recursos predeterminados.
  • Se describen varios recursos en los archivos del directorio values/.
  • Se define un único recurso en cada campo secundario del elemento.
  • Tus recuerdos predeterminados son los que se guardan en los subdirectorios definidos.

En los archivos del directorio values/ se describen varios recursos.
En cada campo secundario del elemento, se define un único recurso
En los subdirectorios definidos, se guardan tus recursos predeterminados.

En los archivos del directorio values/ se describen varios recursos
En cada campo secundario del elemento <resources> se define un único recurso
En los subdirectorios definidos se guardan tus recursos predeterminados

Se describen los recursos en los archivos del directorio values/.
En cada campo secundario del elemento se define un unico recurso<resources>
Los subdirectorios definidos guardan tus recursos predeterminados.

Los recursos son descritos en los archivos del directorio values/
El elemento <resource> define un recurso por cada campo secundario
Tus recursos predeterminados son guardados en el subdirectorio definido

Algunos recursos están descritos en los archivos del directorio values/.
Un solo recurso esta definido en cada campo secundario del elemento .
Los recursos tuyos son predeterminados los recursos que han sido guardados en los subdirectorios definidos.

Se describen varios recursos en los archivos del directorio values/ .
Se define un recurso único en cada campo secundario del elemento <resources>
Se guardan tus recursos predefinidos en los subdirectorios definidos.

  • Varios recursos se describen en los archivos del directorio values/.

  • En cada campo secundario del elemento <resources> se define un único recurso.

  • Son tus recursos predeterminados los recursos que se han guardado en los subdirectorios definidos.

ACTIVO En los archivos del directorio values/ se describen varios recursos
ACTIVO El elemento <resources> tiene definido un único recurso en cada campo secundario.
ACTIVO Los recursos que han sido guardados en los subdirectorios definidos son tus recursos predeterminados

  • En los archivos del directorio values se describen varios recursos
  • En cada campo secundario del elemento resources se define solamente un recurso.
  • Los recursos guardados en los subdirectorios serán marcados como tus recursos predeterminados.
  1. En los archivos del directorio values/ se describen varios recursos.
  2. En cada campo secundario del elemento <resources> un único recurso se define.
  3. Los recursos guardados en los subdirectorios definidos son tus recursos predeterminados.

Acá está mi solución al reto de esta clase, espero haberlo hecho bien:
Los archivos del directorio values/ describen varios recursos.
Cada campo secundario del elemento define un único recurso.
Los subdirectorios guardan tus recursos predeterminados.
Si alguien logra ver algún error, estoy abierto a opiniones.

En los archivos del directorio values/ se describen varios recursos.
Se define un único recurso cada campo secundario del elemento.
Se guardan en los subdirectorios definidos tus recursos predeterminados.

  • Los archivos del directorio values/. describen varios recursos
    *Cada campo secundario del elemento describe un único recurso
    *Los subdirectorios definidos guardan tus recursos predeterminados
  • Los archivos del directorio values/ describen varios recursos
  • Cada campo secundario del elemento define un unico recurso
  • Los subdirectorios definidos guardan turs recursos predeterminados
  • Los archivos del directorio values/ describen varios recursos.
  • Cada campo secundario del elemento define un unico recurso.
  • Los subdirectorios definidos guardan tus recursos predeterminados.
  • Los archivos del directorio values/ describe varios recursos.

  • Definir en cada campo secundario del elemento un unico recurso.

  • Los recursos que se guardan en los subdirectorios definidos serán los recursos predeterminados.

En los archivos del directorio

values/

se describen varios recursos.
En cada campo secundario del elemento se define un único recurso.
En los subdirectorios definidos se gurdan tus recursos predeterminados.

Ejercicio de la clase:

  • Los archivos del directorio values/ describen varios recursos.
  • Cada campo secundario del elemento define un único recurso.
  • Los subdirectorios definidos guardan tus recursos predeterminados.

Creo que está es mejor que la anterior:

• Varios recursos son descritos en los archivos del directorio values/. 
• Los archivos del directorio values/ describen varios recursos.
• Un único recurso es definido en cada campo secundario del elemento 
• Cada campo secundario del elemento define un único recurso.
• Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos. 
• Los subdirectorios definidos han guardado tus recursos predeterminados
• Varios recursos son descritos en los archivos del directorio values/. 
• En los archivos del directorio values/ se describen varios recursos.
• Un único recurso es definido en cada campo secundario del elemento 
• En cada campo secundario del elemento se define un único recurso.
• Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos. 
• En los subdirectorios definidos se han guardado tus recursos predeterminados

• Los archivos del directorio values/ describen arios recursos

• Cada campo secundario del elemento define un único recurso.
• Los subdirectorios definidos guardan tus recursos predeterminados.

  • Los archivos del directorio values/ describen varios recursos.
  • Cada campo secundario del elemento define un único recurso.
  • Tus recursos predeterminados son los recursos a guardar en los subdirectorios definidos.

Respuesta al reto, tratando de seguir la estructura: sujeto + verbo + objetivo:

  • Los recursos se describen en los archivos del directorio values/
  • Se define un solo recurso en cada segundo campo del elemento
  • Tus recursos predeterminados se guardaron en los subdirectorios definidos

Reto de la clase:

  1. Los archivos del directorio values/ describen varios recursos.
  2. Cada campo secundario del elemento define un único recurso.
  3. En los subdirectorios definidos se guardan tus recursos predeterminados.

Solución al reto:

  • Varios recursos son descritos en los archivos del directorio values/.
    • En los archivos del directorio values/ se describen varios recursos.
  • Un único recurso es definido en cada campo secundario del elemento .
    • En cada campo secundario del elemento se define un único recurso
  • Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.
    • En los subdirectorios de definidos se guardan tus recursos predeterminados.

Transformarlos a voz activa

  • Varios recursos son descritos en los archivos del directorio values/.

Voz activa: En los archivos del directorio values/. se describen varios recursos

  • Un único recurso es definido en cada campo secundario del elemento

Voz activa: En cada campo secundario del elemento se define un único recurso

  • Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.

Voz activa: En los subdirectorios definidos han sido guardados los recursos predeterminados.

  1. el directorio values describe varios recursos
  2. el campo secundario del elemento solo define un recurso
  3. los recursos predeterminados son guardados en los subdirectorios definidos
  • Los archivos del directorio values/ describen varios recursos.

  • Cada campo secundario del elemento define un único recurso.

  • Los recursos guardados en los subdirectorios definen los recursos predeterminados.

  • En los archivos del directorio “values/.” se describen varios recursos
  • En cada campo secundario del elemento se define un único recurso
  • Tus recursos han sido guardados en los subdirectorios definidos

Veo que las respuestas de la mayoría son diferentes y se pueden interpretar de distinta forma :S , me pregunto ¿Cuáles respuestas son correctas? y ¿Por que si estoy escribiendo en Markdown mi texto sale pegado? 😦


Pasivo - Varios recursos son descritos en los archivos del directorio values/.

Activo - Varios de los archivos del directorio values/ son recursos descritos


Pasivo - Un único recurso es definido en cada campo secundario del elemento .

Activo - Cada campo secundario del elemento es un único recurso definido.


Pasivo - Son tus recursos predeterminados los recursos que han sido guardados en los subdirectorios definidos.

Activo - Los recursos guardados en los subdirectorios definidos, son predeterminados.

  • Varios recursos se describen en los archivos del directorio values/.
  • Un único recurso se define en cada campo secundario del elemento <resources>.
  • Son tus recursos predeterminados aquellos que se guardan en los subdirectorios definidos.
  1. En los archivos del directorio values/, se describen varios recursos.
  2. Define un único recurso en cada campo secundario del elemento <resources>.
  3. Los recursos que se guardan en los subdirectorios definidos, son recursos predeterminados.

Solución:

  1. Los archivos del directorio values/ se describen varios recursos.
  2. En cada campo secundario del elemento se define un único recurso.
  3. Los recursos que se guardan en los subdirectorios definidos son tus recursos predeterminados.
  • Los recursos se describen en los archivos del directorio values/.

  • en cada campo secundario del elemento se define un unico recurso.

  • Los subdirectorios definidos guardan los recursos predeterminados

Los archivos del directorio values/ varios recursos son descritos (voz activa).
En cada campo secundario del elemento,Un único recurso es definido (voz pasiva)
Los recursos que han sido guardados en los subdirectorios definidos. son predeterminados.(voz activa)

  1. Los archivos del directorio values/ describen varios recursos.
  2. Cada campo secundario del elemento define un único recurso.
  3. Se guardaron tus recursos predeterminados en los subdirectorios definidos
  • Hay varios recursos descritos en los archivos del directorio values/.
  • En cada campo secundario del elemento se describe un único recurso.
  • En los subdirectorios definidos se guardan tus recursos predeterminados.
• En los archivos del directorio values/ son descritos varios recursos.
• En cada campo secundario del elemento se define un único recurso.
• Los recursos guardados en los subdirectorios definidos, son tus recursos predeterminados.

En los archivos del directorio values/. se describen varios recursos.
En cada campo secundario del elemento se define un unico recurso.
Los recursos que han sido guardados en los subdirectorios definifos son tus recursos predeterminados.

  • Los archivos del directorio values/ describen varios recursos

  • Cada campo secundario del elemento define un unico recurso

  • Los subdirectorios definidos guardan los recursos predeterminados

En los archivos del directorio varios recursos son descritos.
En cada campo secundario del elemento un único recurso es defnido.
Los recursos que han sido guardados en los subdirectorios definidos son tus recursos predeterminados.

En los archivos del directorio values/. se describen varios recursos.

En cada campo secundario del elemento se define un único recurso.

En los subdirectorios definidos se han guardado tus recursos predeterminados.

  • En los archivos del directorio varios recursos son descritos.
  • En cada campo secundario del elemento un único recurso es definido.
    -Los recursos que han sido guardados en los subdirectorios definido son tus recursos predeterminados
  • En los archivos del directorio values/ se describen varios recursos.

  • En cada campo secundario del elemento se define un único recurso.

  • Los recursos que han sido guardados en los subdirectorios definidos son tus recursos determinados.

  • En el directorio values/ estan descritos varios recursos.

  • En cada campo secundario del elemento esta definido un único recurso.

  • Los recursos guardados en los subdirectorios definidos son tus recursos predeterminados.

En los archivos del directorio values/, se describen varios recursos

En cada campo secundario del elemento se define un único recurso.

En los subdirectorios definidos se han guardado los recursos predeterminados

Muy buena explicación acerca de la voz activa y la voz pasiva.