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

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

13/20

Lectura

Ahora que tienes ubicados los conceptos básicos de programación, vamos a documentar una función. Una función normalmente cuenta con cada uno de los conceptos que vimos en una clase anterior: diferentes tipos de datos, variables y operadores.

¿Qué es una función? 📦

Una función es un conjunto de procedimientos encapsulados en un bloque de código, usualmente reciben parámetros, cuyos valores se utilizan para efectuar tareas específicas y adicionalmente retornan un valor.

Si eres programadora o technical writer, es importante saber documentar bloques de código. Esta actividad añade suficiente información para explicar lo que hace el código punto por punto, de forma que no solo las computadoras sepan qué hacer, sino que los humanos también lo entiendan (y por qué).

En el caso de las funciones, es vital documentarlas para saber cuál es la tarea que realizan, cuáles son los parámetros que reciben y qué es lo que nos devuelven.

Hay un mito que circula dentro del círculo de programadores: si tú escribes tu código claramente, usas una estructura apropiada y convenciones de nomenclatura adecuadas, con eso es suficiente para llamarle auto-documentación. Claramente no es cierto, solamente contribuye en gran medida a que el código sea fácil de leer, pero no significa que esté documentado.

Cada lenguaje de programación maneja diferentes estándares para documentar, en los ejemplos que hemos visto en este curso nos hemos basado en JavaScript, así que seguiré por esa línea.

JavaScript tiene un formato estándar para la documentación llamado JSDoc. Para el caso de las funciones te presento los siguientes formatos.

Comentarios multilínea en cabeceras de funciones 💆🏼‍♀️

Para comentar lo que hace una función usaremos comentarios de este tipo:

  • El comentario comienza con una barra y dos asteriscos (/**).

  • Cada nueva línea lleva un asterisco al comienzo (*).

  • Escribe una descripción al principio para describir la función.

  • La descripción de un parámetro se hace comenzando con @param.

  • Si una línea es demasiado larga, la dividimos en varias líneas. La primera estará sin indentar y el resto indentada (desplazada hacia dentro) respecto a la primera.

  • El comentario cierra con un asterisco y una barra diagonal (*/).

  • Los comentarios puntuales sobre una línea de código se harán con dos barras inclinadas (//).

Si seguimos esa regla, la estructura quedaría así:


/**

* [algunaFuncion descripción]

* @param {[tipoDeDato]} nombredeParametro1 [descripción]

* @param {[tipoDeDato]} nombredeParametro2 [descripción]

* @return {[tipoDeDato]} [descripción]

*/

var algunaFuncion = function (nombredeParametro1, nombredeParametro2) {

// Hace algo...

};

Este es otro ejemplo de este mismo formato aplicado a una función real:


/**

* Agregar dos números y sumarlos

* @param {number} num1 El primer número

* @param {number} num2 El segundo número

* @return {number} El total de los dos números ingresados

*/

var sumarDosNumeros = function (num1, num2) {

return num1 + num2;

};

Usa etiquetas normalizadas 🕺

Cuando queramos agregar una descripción de un elemento usaremos etiquetas normalizadas. Por ejemplo, una etiqueta normalizada para describir un parámetro es @param. Siguiendo esa norma, tiene que escribirse tal cual, no puede ser normalizada si usamos @Parametro, @parametros o variaciones por el estilo.

Las etiquetas normalizadas más comunes son:

technical-writing7.png

Sobre documentar vs. sub documentar: ¿añado información adicional? 👽

Usar el formato estándar JSDoc nos da una visión general de la función principal. Algunas veces con eso es suficiente, nuestra función sumarDosNumeros(), por ejemplo, está completamente descrita por el encabezado “Agregar dos números y sumarlos”.

Para funciones ligeramente más grandes es útil añadir comentarios de una línea (o a veces de varias) dentro de nuestra función para describir todo lo que está sucediendo.

Esto puede parecer exagerado para algunos programadores, pero tu yo del futuro siempre le agradecerá a tu yo del pasado por hacer esto cuando vuelvas a un proyecto que no has tocado en algún tiempo. Nunca te preguntarás qué hace una línea de código o por qué la escribiste. Definitivamente es preferible tener código sobre-documentado que sub-documentado.

Aquí un ejemplo de otra función, ¿podrías decirme qué dice cada línea?


/**

* Cambiar la visibilidad de una pestaña de contenido

* @param {string} selector Selector para el elemento

* @param {node} toggle El elemento que disparó la pestaña

*/

var toggleVisibility = function (selector, toggle) {

if (!selector) return;

var elem = document.querySelector(selector);

if (!elem) return;

elem.classList.add('active');

if (toggle) {

toggle.classList.add('active');

}

elem.focus()

if (document.activeElement.matches(selector)) return;

elem.setAttribute('tabindex', '-1');

elem.focus();

};

Si estás familiarizado con el código, quizás podrías entenderlo. Pero, si no, te tomaría algo de tiempo hacerlo. Aquí un ejemplo con algo de sobre-documentación:


/**

* Cambiar la visibilidad de una pestaña de contenido

* @param {string} selector Selector para el elemento

* @param {node} toggle El elemento que dispara la pestaña

*/

var toggleVisibility = function (selector, toggle) {

  

// Si no hay un selector, termina

if (!selector) return;

  

// Consigue que se muestre la pestaña

var elem = document.querySelector(selector);

if (!elem) return;

  

// Muestra el elemento

elem.classList.add('active');

  

// Si un elemento toggle fue dado, agrega un .active class para el estilo

if (toggle) {

toggle.classList.add('active');

}

  

// Trae el nuevo elemento dentro de focus

elem.focus()

  

// Si elem.focus() no funciona, agrega tabindex="-1" e intenta nuevamente

// (los elementos que no son focus por defecto necesitan una tabindex)

if (document.activeElement.matches(selector)) return;

elem.setAttribute('tabindex', '-1');

elem.focus();

  

};


En la próxima clase pondremos en práctica lo aprendido con algunos ejemplos, ejercicios y desafíos. ¡Allá te espero!

Aportes 12

Preguntas 0

Ordenar por:

Los aportes, preguntas y respuestas son vitales para aprender en comunidad. Regístrate o inicia sesión para participar.

Tu yo del futuro siempre le agradecerá a tu yo del pasado por hacer esto cuando vuelvas a un proyecto que no has tocado en algún tiempo … ¡Frase del día!

Este es uno de los errores que cometen las personas que están empezando en el mundo de la programación. Tienden a no comentar su código. Una vez regresan después de 3 o 6 meses, solo dios sabe que hicieron o para que sirve el programa.

Soy de las que creía en el mito de si escribes tus variables y funciones coherentemente y las haces entendibles y no es necesario documentaras, es bueno saber que el mito es falso.

No conocía el JSDoc, con este nuevo conocimiento podre documentar mis programas.

📌 Definitivamente es preferible tener código sobre-documentado que sub-documentado.

Gracias, no conocía que existía este tema en cada lenguaje de programación buscaré el correspondiente a los que yo trabajo para comenzar a aplicarlo.

Tu yo del futuro siempre le agradecerá a tu yo del pasado

Los comentarios en el código son fundamentales, otra documentación que aprendí son los sitemas de diseño para documentar estilos, componentes, etc. Dejo el curso: https://platzi.com/clases/sistemas-diseno/

Yo también había escuchado acerca de ese mito

Me sentía abrumada pensando en que debía conocer de todos los lenguajes para poder ser buena TW, ¡pero ta vi que no! A quitarse el miedo.