Redacción técnica para principiantes: una guía de AZ sobre conceptos básicos de blogs tecnológicos

Si te encanta la escritura y la tecnología, la escritura técnica podría ser una carrera adecuada para ti. También es algo más que puedes hacer si te encanta la tecnología pero no te apetece codificar todo el día.

La redacción técnica también puede ser para ti si te encanta aprender enseñando a otros, contribuyendo a proyectos de código abierto y enseñando a otros cómo hacerlo también, o básicamente disfrutas explicando conceptos complejos de manera simple a través de tu escritura.

Profundicemos en los fundamentos y aprendamos sobre lo que debe saber y considerar al comenzar con la redacción técnica.

Tabla de contenido

En este artículo, veremos:

  • Qué es la escritura técnica
  • Beneficios de la redacción técnica
  • Habilidades necesarias para tener como escritor técnico
  • El proceso de redacción técnica
  • Plataformas para publicar sus artículos
  • Cursos de redacción técnica
  • Foros y comunidades de redacción técnica
  • Algunos escritores técnicos increíbles a seguir
  • Palabras finales y referencias

¿Qué es la escritura técnica?

La escritura técnica es el arte de proporcionar instrucción orientada a los detalles para ayudar a los usuarios a comprender una habilidad o un producto específico.

Y un escritor técnico es alguien que escribe estas instrucciones, también conocidas como documentación técnica o tutoriales. Esto podría incluir manuales de usuario, artículos de soporte en línea o documentos internos para codificadores / desarrolladores de API.

Un escritor técnico se comunica de una manera que presenta información técnica para que el lector pueda usar esa información para un propósito previsto.

Beneficios de la redacción técnica

Los escritores técnicos son aprendices de por vida. Dado que el trabajo implica comunicar conceptos complejos en términos simples y directos, debe estar bien versado en el campo sobre el que está escribiendo. O estar dispuesto a aprender sobre ello.

Esto es genial, porque con cada nuevo documento técnico que investigue y escriba, se convertirá en un experto en ese tema.

La redacción técnica también te da una mejor sensación de empatía con el usuario. Le ayuda a prestar más atención a lo que sienten los lectores o usuarios de un producto que a lo que usted piensa.

También puede ganar dinero como redactor técnico contribuyendo a organizaciones. Aquí hay algunas organizaciones que le pagan por escribir para ellos, como Smashing Magazine, AuthO, Twilio y Stack Overflow.

Además de todo esto, puede contribuir a las comunidades de código abierto y participar en programas de código abierto pagados como Google Season of Docs y Outreachy.

También puede dedicarse a la redacción técnica como una profesión a tiempo completo; muchas empresas necesitan a alguien con esas habilidades.

Habilidades necesarias para tener como escritor técnico

Comprender el uso del inglés adecuado

Antes de considerar la escritura, es necesario tener una buena comprensión del inglés, sus tiempos verbales, ortografía y gramática básica. Sus lectores no quieren leer un artículo plagado de gramática incorrecta y mala elección de palabras.

Saber explicar las cosas de forma clara y sencilla.

Saber cómo implementar una función no significa necesariamente que pueda comunicar claramente el proceso a los demás.

Para ser un buen maestro, debe ser empático, con la capacidad de enseñar o describir términos de manera adecuada para su público objetivo.

Si no puede explicárselo a un niño de seis años, no lo entiende usted mismo. Albert Einstein

Poseer algunas habilidades de escritura‌‌

Creo que los escritores se hacen, no nacen. Y solo puedes aprender a escribir escribiendo realmente.

Es posible que nunca sepa que tiene la capacidad de escribir hasta que ponga la pluma sobre el papel. Y solo hay una forma de saber si tienes algunas habilidades de escritura, y es escribiendo.

Así que te animo a que empieces a escribir hoy. Puede elegir comenzar con cualquiera de las plataformas que enumeré en esta sección para estirar los músculos de la escritura.

Y, por supuesto, también es una gran ventaja tener algo de experiencia en un campo técnico.

El proceso de redacción técnica

Analiza y comprende quiénes son tus lectores

El factor más importante a considerar cuando escribe un artículo técnico es su audiencia prevista / esperada. Siempre debe estar al frente de su mente.

Un buen escritor técnico escribe basándose en el contexto del lector. Como ejemplo , digamos que está escribiendo un artículo dirigido a principiantes. Es importante no asumir que ya conocen ciertos conceptos.

Puede comenzar su artículo describiendo los requisitos previos necesarios. Esto asegurará que sus lectores tengan (o puedan adquirir) el conocimiento que necesitan antes de sumergirse directamente en su artículo.

También puede incluir enlaces a recursos útiles para que sus lectores puedan obtener la información que necesitan con solo un clic.

Para saber para quién está escribiendo, debe recopilar la mayor cantidad de información posible sobre quién utilizará el documento.

Es importante saber si su audiencia tiene experiencia en el campo, si el tema es totalmente nuevo para ellos o si se encuentran en algún punto intermedio.

Sus lectores también tendrán sus propias expectativas y necesidades. Debe determinar qué busca el lector cuando comience a leer el documento y qué obtendrá de él.

Para comprender a su lector, hágase las siguientes preguntas antes de comenzar a escribir:

  • ¿Quiénes son mis lectores?
  • ¿Que necesitan?
  • ¿Dónde estarán leyendo?
  • ¿Cuándo estarán leyendo?
  • ¿Por qué estarán leyendo?
  • ¿Cómo estarán leyendo?

Estas preguntas también lo ayudan a pensar en la experiencia de su lector mientras lee su escritura, de la que hablaremos más ahora.

Piense en la experiencia del usuario

La experiencia del usuario es tan importante en un documento técnico como en cualquier lugar de la web.

Ahora que conoce a su audiencia y sus necesidades, tenga en cuenta cómo el documento en sí satisface sus necesidades. Es muy fácil ignorar cómo el lector utilizará realmente el documento.

Mientras escribe, retroceda continuamente y vea el documento como si fuera el lector. Pregúntese: ¿es accesible? ¿Cómo lo usarán sus lectores? ¿Cuándo lo usarán? ¿Es fácil de navegar?

El objetivo es escribir un documento que sea útil y utilizable para sus lectores.

Planifique su documento

Teniendo en cuenta quiénes son sus usuarios, puede conceptualizar y planificar su documento.

Este proceso incluye una serie de pasos, que repasaremos ahora.

Realizar una investigación exhaustiva sobre el tema.

Mientras planifica su documento, debe investigar el tema sobre el que está escribiendo. Hay toneladas de recursos a solo una búsqueda de Google para que los consuma y obtenga información más detallada.

No caigas en la tentación de quitar los trabajos o artículos de otras personas y hacerlos pasar por tuyos, ya que esto es plagio. Más bien, utilice estos recursos como referencias e ideas para su trabajo.

Busque en Google tanto como sea posible, obtenga datos y cifras de revistas de investigación, libros o noticias, y recopile toda la información que pueda sobre su tema. Entonces puedes empezar a hacer un esquema.

Hacer un esquema

Resumir el contenido de su documento antes de ampliarlo le ayuda a escribir de una manera más enfocada. También le permite organizar sus pensamientos y lograr sus objetivos para su escritura.

Un esquema también puede ayudarlo a identificar lo que desea que sus lectores obtengan del documento. Y finalmente, establece una línea de tiempo para completar su escritura.

Obtenga gráficos / imágenes relevantes

Tener un esquema es muy útil para identificar las diversas ayudas virtuales (infografías, gifs, videos, tweets) que necesitará incrustar en diferentes secciones de su documento.

Y hará que su proceso de escritura sea mucho más fácil si mantiene estos gráficos relevantes a mano.

Escribe con el estilo correcto

¡Por fin puedes empezar a escribir! Si ha completado todos estos pasos, la escritura debería ser mucho más fácil. Pero aún debe asegurarse de que su estilo de escritura sea adecuado para un documento técnico.

La redacción debe ser accesible, directa y profesional. El texto florido o emotivo no es bienvenido en un documento técnico. Para ayudarlo a mantener este estilo, aquí hay algunas características clave que debe cultivar.

Usar voz activa

Es una buena idea utilizar voces activas en sus artículos, ya que es más fácil de leer y comprender que la voz pasiva.

Voz activa significa que el sujeto de la oración es el que realiza activamente la acción del verbo. La voz pasiva significa que un sujeto es el receptor de la acción de un verbo .

Este es un ejemplo de voz pasiva : todos los desarrolladores web deben leer la documentación seis veces al año.

Y aquí hay un ejemplo de voz activa : todo desarrollador web debería leer esta documentación 6 veces al año.

Elija sus palabras con cuidado

La elección de palabras es importante. Asegúrese de utilizar la mejor palabra para el contexto. Evite el uso excesivo de pronombres como 'eso' y 'esto' ya que el lector puede tener dificultades para identificar a qué sustantivos se refiere.

También evite la jerga y el lenguaje vulgar: recuerde que está escribiendo para un público más amplio cuya disposición e inclinaciones culturales podrían diferir de las suyas.

Evite la jerga excesiva

Si es un experto en su campo, puede ser fácil utilizar la jerga con la que está familiarizado sin darse cuenta de que puede resultar confuso para otros lectores.

También debe evitar el uso de siglas que no haya explicado anteriormente.

He aquí un ejemplo :

Menos claro: las PWA se consideran verdaderamente el futuro del desarrollo multiplataforma. Su disponibilidad tanto en Android como en iOS los convierte en la aplicación del futuro.

Mejorado: las aplicaciones web progresivas (PWA) son realmente el futuro del desarrollo multiplataforma. Su disponibilidad tanto en Android como en iOS hace de PWA la aplicación del futuro.

Utilice un lenguaje sencillo

Use menos palabras y escriba de manera que cualquier lector pueda entender el texto. Evite las palabras grandes y largas. Intente siempre explicar conceptos y términos de la forma más clara posible.

Formateo visual

Una pared de texto es difícil de leer. Incluso las instrucciones más claras se pueden perder en un documento que tiene una representación visual deficiente.

Dicen que una imagen vale más que mil palabras. Esto suena cierto incluso en la redacción técnica.

Pero no cualquier imagen es digna de un documento técnico. La información técnica puede ser difícil de transmitir solo en texto. Una imagen o diagrama bien ubicado puede aclarar su explicación.

A las personas también les encantan las imágenes, por lo que es útil insertarlas en los lugares correctos. Considere las siguientes imágenes:

Primero, aquí hay un fragmento de blog sin imágenes:

Aquí hay un fragmento del mismo blog, pero con imágenes:

Agregar imágenes a sus artículos hace que el contenido sea más identificable y más fácil de entender. Además de las imágenes, también puede utilizar gifs, emoji, incrustaciones (redes sociales, código) y fragmentos de código cuando sea necesario.

El formato, las plantillas y las imágenes o diagramas cuidadosos también harán que su texto sea más útil para sus lectores. Puede consultar las referencias a continuación para obtener una plantilla de redacción técnica de @Bolajiayodeji.

Haga una revisión cuidadosa

La buena redacción de cualquier tipo debe estar libre de errores ortográficos y gramaticales. Estos errores pueden parecer obvios, pero no siempre es fácil detectarlos (especialmente en documentos extensos).

Siempre verifique su ortografía (ya sabe, coloque los puntos en sus Is y cruce sus Ts) antes de presionar "publicar".

Hay una serie de herramientas gratuitas como Grammarly y la aplicación Hemingway que puede usar para verificar errores gramaticales y ortográficos. También puede compartir un borrador de su artículo con alguien para que lo revise antes de publicarlo.

Dónde publicar sus artículos

Ahora que ha decidido dedicarse a la redacción técnica, aquí hay algunas buenas plataformas en las que puede comenzar a publicar contenido técnico de forma gratuita. También pueden ayudarlo a crear una cartera atractiva para que los futuros empleadores la revisen.

Dev.to es una comunidad de miles de expertos en tecnología en la que tanto escritores como lectores pueden participar y compartir ideas y recursos de manera significativa.

Hashnode es mi plataforma de blogs de referencia con ventajas increíbles, como mapeo de dominio personalizado y una comunidad interactiva. Crear un blog en esta plataforma también es fácil y rápido.

freeCodeCamp tiene una gran comunidad y alcance de audiencia y es un gran lugar para publicar sus artículos. Sin embargo, deberá solicitar la redacción de su publicación con algunas muestras de redacción anteriores.

Su solicitud puede ser aceptada o rechazada, pero no se desanime. Siempre puede volver a aplicar más tarde a medida que mejora, y ¿quién sabe? Podrías ser aceptado.

Si escribe para ellos, revisarán y editarán sus artículos antes de publicarlos, para asegurarse de que publique el artículo más pulido posible. También compartirán sus artículos en sus plataformas de redes sociales para ayudar a más personas a leerlos.

Hackernoon tiene más de 7.000 escritores y podría ser una gran plataforma para que comiences a publicar tus artículos para los más de 200.000 lectores diarios de la comunidad.

Hacker Noon apoya a los escritores revisando sus artículos antes de publicarlos en la plataforma, ayudándolos a evitar errores comunes.

Cursos de redacción técnica

Al igual que en cualquier otro campo, existen varios procesos, reglas, mejores prácticas, etc. en la redacción técnica.

Tomar un curso de redacción técnica lo ayudará a guiarlo a través de todo lo que necesita aprender y también puede brindarle un gran impulso de confianza para comenzar su viaje de escritura.

Aquí hay algunos cursos de redacción técnica que puede consultar:

  • Curso de redacción técnica de Google (gratuito)
  • Curso de redacción técnica de Udemy (pago)
  • Bootcamp de escritura técnica de Hashnode (gratis)

Foros y comunidades de redacción técnica

Solos podemos hacer tan poco, juntos podemos hacer tanto ~ Helen Keller

Ser parte de una comunidad o foro junto con personas que comparten la misma pasión que tú es beneficioso. Puede obtener comentarios, correcciones, consejos e incluso aprender algunos consejos de estilo de otros escritores de la comunidad.

Aquí hay algunas comunidades y foros a los que puede unirse:

  • Hashnode
  • Dev.to
  • Mundo de la escritura técnica
  • Foro de redactores técnicos
  • Escribe el Foro de Documentos

Algunos escritores técnicos asombrosos a seguir

En mi viaje de escritura técnica, vine y seguí a grandes escritores técnicos cuyo viaje de escritura, consistencia y estilo me inspiran.

Estos son los escritores a quienes admiro y considero mentores virtuales en redacción técnica. A veces, dejan caer consejos de redacción técnica que encuentro útiles y de los que he aprendido mucho.

Estos son algunos de esos escritores (hipervínculos con sus identificadores de Twitter):

  • Quincy Larson
  • Edidiong Asikpo
  • Pozo catalin
  • Victoria Lo
  • Bolaji Ayodeji
  • Amruta Ranade
  • Chris Bongers
  • Colby Fayock

Ultimas palabras

No necesita un título en redacción técnica para comenzar a publicar contenido técnico. Puede comenzar a escribir en su blog personal y en los repositorios públicos de GitHub mientras crea su portafolio y obtiene experiencia práctica.

Realmente, solo empieza a escribir.

Practique creando nuevos documentos para programas o proyectos existentes. Hay una serie de proyectos de código abierto en GitHub que puede consultar y agregar a su documentación.

¿Hay alguna aplicación que le guste usar, pero su documentación está mal escrita? Escriba el suyo y compártalo en línea para recibir comentarios. También puede configurar rápidamente su blog en hashnode y comenzar a escribir.

Aprendes a escribir escribiendo y leyendo y pensando en cómo los escritores han creado sus personajes e inventado sus historias. Si no eres lector, ni siquiera pienses en ser escritor. - Jean M. Auel

Los escritores técnicos siempre están aprendiendo . Al sumergirse en nuevas áreas temáticas y recibir comentarios externos, un buen escritor nunca deja de perfeccionar su oficio.

Por supuesto, los buenos escritores también son lectores voraces. Al revisar documentos muy leídos o muy utilizados, su propia escritura definitivamente mejorará.

¡No puedo esperar a ver sus artículos técnicos!

Referencias

Introducción a la redacción técnica‌‌

Cómo estructurar un artículo técnico‌‌

Comprender a su audiencia, el por qué y el cómo

‌‌Plantilla de escritura técnica

Espero que esto haya sido de ayuda. Si es así, sígueme en Twitter y avísame.