70

¿Qué es Technical Writing? Cómo escribir documentación para equipos de programación profesional

211914Puntos

hace 4 años

El technical writing o escritura técnica consiste en traducir ideas complejas a un lenguaje fácil de entender para tus usuarios. Aunque casi siempre lo relacionamos con la documentación de código y manuales de software, nuestro trabajo tiene muchísimas otras aplicaciones, como enseñar a manejar programas informáticos, operar equipos industriales o incluso evaluar condiciones médicas.

Estudiar escritura técnica te ayudará a crecer profesionalmente

Saber escribir documentos técnicos es una gran habilidad para tu perfil profesional. No solo nos sentamos a escribir un día y al otro tenemos lista la documentación. Escribir, de hecho, ni siquiera es el primer paso.

Como technical writers debemos adentrarnos en un flujo de trabajo muy completo. Realizamos entrevistas y muchos procesos de investigación para comprender a profundidad la herramienta o rutina que debemos documentar. Luego estudiamos a nuestra audiencia, conocemos su contexto, limitaciones y objetivos para saber exactamente cuáles son sus problemáticas a resolver.

Lo más bonito es que este trabajo tiene una de las mejores recompensas: podrás ver el éxito de tus usuarios gracias a la gran comunicación y empatía que tuviste con ellos.

No supongas nada, comprende a tu público objetivo

Technical writing y público objetivo

Escribir documentos técnicos es como dar una clase. Además de ser expertas en el tema, las profesoras necesitan mucha información sobre sus estudiantes: qué edad tienen, cuánto saben sobre la herramienta o proceso que vamos a aprender, a qué nivel de experticia deben llegar cuando terminemos, entre otros.

Recuerda que hablar el mismo idioma no siempre significa entender el mismo lenguaje. Así como no le hablas igual a un estudiante de primaria que a uno de bachillerato, no debes asumir que un estudiante principiante de Python entenderá los mismos conceptos que una experta en análisis de datos.

Como technical writer tienes una audiencia que está ahí contigo porque tiene una meta que alcanzar o un problema que resolver. La falta de análisis y hacer suposiciones sobre tu público es un problema recurrente que debemos evitar por el bien de tus lectores o estudiantes.

Si no tienes muy claro quién es tu audiencia, no podrás comunicarte correctamente con ellos y todo tu trabajo habrá sido en vano.

Technical writing aplicado a documentación de código

Existen dos tipos de documentación: documentación para terceros (como herramientas open-source) y documentación del código fuente (como proyectos personales y software privado).

La documentación para terceros es, valga la redundancia, documentación para que otra persona pueda utilizar el código que creaste tú (o tu equipo de programación). Aquí es indispensable que estudies muy bien quién es el público al que va orientada esta herramienta para que tu explicación sea comprensible.

La sintaxis estándar para escribir este tipo de documentación es Markdown. Esta herramienta (casi un lenguaje) es muy poderosa, así que estudiarla profundamente te permitirá sacarle todo el provecho. Además, si tu documentación es muy grande, también debes aprender a organizar el contenido de tus documentos para que las lecturas no sean tan largas ni demasiado cortas y toda la información sea fácil de encontrar.

Recuerda implementar un buen sistema de revisión y testeo de tu documentación para evitar problemas de información desactualizada o código obliterado.

Al escribir documentación del código fuente casi siempre escribimos nuestra documentación en el mismo lugar que el código utilizando comentarios y siguiendo algunas convenciones para que cualquier desarrollador del equipo la pueda entender y, además, para que se integre correctamente con herramientas de desarrollo (como VSCode).

Tu código debe ser fácil de entender, por eso seguimos convenciones y buenas prácticas de programación. Pero no te engañes. El código autocomentado es un mito, siempre debes documentar. Incluso el código más sencillo en un lenguaje de programación tan fácil de leer como Python puede volverse una pesadilla completamente inentendible si no le dedicas tiempo a escribir una buena documentación.

¿Problemas con las tildes? Mira estos ejemplos de palabras esdrújulas

¿Cómo convertirte en Technical Writer profesional?

Curso de technical writing

Aunque puedes dedicarte al technical writing de tiempo completo, también puedes estudiarlo como una nueva habilidad para tu carrera como desarrolladora de software. Todos los equipos de programación necesitan documentación y convirtiéndote en technical writer tienes una oportunidad para destacar en esta área.

Puedes dar el primer paso tomando el Curso de Introducción al Technical Writing y Documentación con Markdown. Vamos a profundizar en cada uno de los temas que te acabo de comentar: cómo estudiar y definir muy bien a nuestra audiencia, documentar código fuente y para terceros, estructuras gramaticales y buenas prácticas de redacción y mucho más. Además, puedes profesionalizarte en cada una de tus responsabilidades como technical writer siguiendo la ruta de aprendizaje que te dejo en la sección de comentarios.

¡Te espero en el curso!

#NuncaParesDeAprender 🤓💚

Juan
Juan
juandc

211914Puntos

hace 4 años

Todas sus entradas
Escribe tu comentario
+ 2
Ordenar por:
25
4

Quiero tomar el curso después del curso de JS Profesional, estoy emocionado por este curso 😃

3

Un profesor, decía en la universidad, que es algo fundamental tener un código bien documentado, para que cualquier otro desarrollador lo pueda usar, o bien, para que tu mismo puedas irlo mejorando, porque, inevitablemente, tarde o temprano puedes llegar a perderte u olvidar que es lo que hiciste en su momento, y que mejor que tener una técnica para hacer este proceso.

2
14787Puntos

This is amazing!

2
8371Puntos

Impecable Juan, como siempre. Saludos.

2
19392Puntos

Esta muy genial para cuando termine mi ruta de aprendizaje de dato science (la cual me esta costando horrores)

2
29787Puntos

Este curso me emociona muchísimo, es muy interesante aprender a documentar de forma apropiada. Lo voy a iniciar hoy mismo 😃

2
211914Puntos
4 años

¡Me alegra mucho oír eso! 👏