Clase 14 de 20 • Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
En esta clase aprenderemos a documentar código de muestra de una manera legible. El objetivo es proporcionar calidad y coherencia en toda tu documentación, no funcionalidad. El código de muestra sirve como un mini-portal al contenido de una documentación completa.
Los programadores utilizan el código de muestra (como documentación) para iniciarse rápidamente en el uso de la herramienta y casi siempre navegan por el código antes de leer un tema en su totalidad. Debido a su especial consideración, el código de muestra requiere mucha atención.
Por otra parte, un bloque de código es una pieza de un código de muestra, posiblemente de una o unas pocas líneas, como la función que documentamos en una clase anterior. La documentación de bloques de código con el tiempo termina por difuminarse, ya que los equipos no suelen probar los bloques de código con el mismo rigor que los códigos de muestra completos, así que, por esta razón, nos enfocaremos más en este último concepto.
Creando un código de muestra correcto 🏄♂️
Un buen código de muestra es frecuentemente la mejor documentación para los programadores. No importa si los párrafos y listas de tu documentación son claros, los programadores prefieren mil veces un buen código de muestra. Después de todo, el texto y el código son lenguajes diferentes y es el código de muestra lo que en última instancia le importa al lector.
Al documentar código de muestra debemos de ser correctos y concisos para que nuestros lectores lo entiendan rápidamente y lo reutilicen fácilmente sin tener efectos secundarios. Para ello, el código de muestra debe cumplir las siguientes características:
El código de muestra es una oportunidad para influir directamente en la forma en la que los programadores están escribiendo el código. Por lo tanto, el código establecerá parte de la calidad del software. Si eres programadora, considera los pros y contras en caso de que tengas más de una forma de programar una función. Codifica sobre la decisión que sea la mejor y la más legible.
Un bloque de código es una pieza de un código de muestra, posiblemente de una o unas pocas líneas de largo, como la función que documentamos en la clase "Documentando una función". La documentación de bloques de código con el tiempo termina por difuminarse porque los equipos no suelen probar los bloques de código con el mismo rigor que los códigos de muestra completos.
Averigua cuál es el caso primario de lo que el código de muestra debe hacer. Habla con los programadores y directores del proyecto, lee los requisitos y los comentarios del código.
Siempre prueba el código de muestra. Los sistemas adquieren mantenimiento, por lo que el código fuente puede cambiar sobre la marcha y el código muestra dejará de funcionar. Muchos equipos reciclan sus pruebas unitarias y los toman como código de muestra, eso es una mala idea. El objetivo principal de una prueba unitaria es probar; el único objetivo de un código de muestra es educar al usuario.
Código ejecutable 🚀
Cuando documentas el código de muestra debes explicar cómo ejecutarlo. Es posible que en el documento tengas que indicar a los usuarios que realicen actividades previas antes de ejecutar el código de muestra, como las siguientes:
Pero no siempre los usuarios realizan correctamente las actividades anteriores. En algunas situaciones los usuarios prefieren ejecutar código de muestra directamente antes que leer la documentación. Y justo cuando algo no les es comprensible, ahora sí, pasan a leer la documentación.
Esto me recuerda un estudio realizado por Acens, una empresa de tecnologías cloud, que muestra que el 75% de los usuarios reconoce que no lee el manual de instrucciones de los equipos y los dispositivos que adquieren hasta que se les atraviesa una falla.
Recuerda tomar capturas de pantalla del código en acción. Suelen ser útiles para dar a los lectores una idea del objetivo del código de muestra y de lo que la herramienta puede hacer.
Código conciso y comprensible 🤓
El código de la muestra debe ser conciso, lo ideal es que incluyas solo los componentes esenciales. El código irrelevante puede distraer y confundir a tu lector. Recuerda que esta sugerencia no es sinónimo para que los programadores o tú hagan malas prácticas para acortar el código.
Un código de muestra debe de ser comprensible, por lo que es importante contar con las siguientes características:
Código comentado 📋
Considera las siguientes recomendaciones sobre los comentarios en el código de muestra:
En la medida de lo posible ten todo el código necesario en un solo bloque para que los lectores puedan copiar y pegar fácilmente. Ten en cuenta que este tipo de lectores no solo recogen el código, también cualquier comentario insertado.
Los comentarios dentro del código son un gran medio de comunicación técnica. Por lo tanto, pon cualquier descripción que pertenezca al código pegado dentro de los comentarios del código. Por el contrario, cuando tengas que explicar un concepto extenso o complicado pon el texto antes del programa de ejemplo.
Tal vez lo más importante es que te veas a ti mismo como el defensor o representante de aquellos desarrolladores que necesitan usar la API o la herramienta que estás ilustrando. Piensa en las preguntas que te harían si tuvieran acceso a las herramientas que tú usas y pon las respuestas en la documentación + el código de muestra.
Código reutilizable ♻️
Para que tu lector pueda reutilizar fácilmente el código de muestra solicita a las programadoras lo siguiente:
El ejemplo y el anti-ejemplo 🙅♂️
Además de mostrar a los lectores lo que deben hacer con el código de muestra, a veces es prudente mostrar a los lectores lo que NO deben hacer.
Por ejemplo, algunos lenguajes de programación permiten a los programadores poner punto y coma (;) al final de cada instrucción. Supongamos que estás escribiendo un tutorial en un lenguaje como JavaScript que no sugiere poner punto y coma al final de cada instrucción. En este caso, mostrar tanto un buen ejemplo como un anti-ejemplo beneficiará al lector. Por ejemplo:
Esta es una función válida con punto y coma al final de la instrucción.
console.log(getName()); function getName(){ return { name: "@davidenq" } };
Y, en cambio, esta es una función inválida porque cuando ejecutemos el código obtendremos como resultado un error del tipo "Uncaught SyntaxError", cuando lo que esperamos como resultado es ‘@davidenq’.
console.log(getName()); function getName(){ return { name: "@davidenq"; }; }
Código secuenciado 🧗♀️
Un buen conjunto de código de muestra puede incrementar el rango de complejidad de su lectura. Los lectores que no están familiarizados con cierta tecnología normalmente necesitan ejemplos simples para empezar.
El primer y más básico ejemplo en un conjunto de código de muestra se suele denominar "Hello, World!". Después de dominar lo básico, los programadores quieren ejemplos más retadores. Así que para que tu documentación sea un buen conjunto de código de muestra, proporciona una buena secuencia de códigos de muestra que vayan subiendo de nivel, desde simples, moderados hasta más complejos.
En el siguiente módulo aprenderemos cómo organizar nuestros documentos definiendo nuestro alcance y audiencia, dividiendo secciones y utilizando markdown para editar nuestro texto. :muscle:
Juan Esteban Galvis
Juan Castro
Gonzalo Gramaglia
Erika Gabriela Villanueva Perez de Leon
Daniel Andres Rojas Paredes
Jorge Cruz Perez
Nicolás Sañudo
Emilia Cabral Benitez
Carlos Eduardo Gomez García
Emilia Cabral Benitez
Gonzalo Gramaglia
Cristian Dario Prieto Avella
Alberto Vargas
Daniel Andres Rojas Paredes
Jeisson Andres Peña Osorio
Este es un ejemplo de cómo yo documento código de muestra:
Colores
Principalmente para unir conceptos y así encontrar el código con la definición o explicación
Comentarios y bloques de código
if no es necesario explicarlo, pero qué hace cada función y la explicación de líneas más complejas si llevan su comentarioTe quedó muy bien. :clap:
Muy bueno 👏👌 Tomo prestado tu código de muestra de expresiones regulares 😁
Tengo una super duda, yo acostumbro a poner cabecera en todas mis clases indicando lo siguiente: ¿Qué opinan sobre esta practica?
<!-- @description : url_de_documentacion_en_git @author : programador_que_creo @group : equipo_responsable_de_proyecto @last modified on : 21-01-2021 @last modified by : programador_que_modifico -->
uso Visual Studio Code y encontré una extensión que ingresa y actualiza la cabecera por mi, se las dejo a quien sea de su interés. Salesforce Documenter
Gracias por tu aporte. agradezco que lo hallas echo en texto y no en captura de pantalla, con la segunda no lo habria podido leer usando el NvDa
Solo hay un punto, no se en que aspecto o contexto lo tratan de expresar, feminismo?? , no se, pero referirse de repente en femenino y en la mayor parte en masculino, creo que no debe ser así, considero que es sin genero, y se entiende, pero creo que hacer ese énfasis descontextualiza la lectura, se que es un punto de debate, y mi intención no es tal, si no concluir que para mi es universal y así evitamos precisamente eso, dar genero a las palabras , saludos :)
Si el genero de las palabras logra "descontextualizar la lectura" en vos, es probable que el problema no sea el texto ni el curso (:
Creo que en todo caso debería ser todo en femenino o en masculino. Pero mantener una coherencia en ese aspecto. Por mi parte voto por femenino, es un texto de un curso no de la RAE, no importa si el masculino en la teoría es sin género. Pero al escribirlo en femenino, cambia el imaginario de que solo los varones programan. Si te digo "hoy me encontré unos programadores" ¿Los imaginas sin género? No creo.
Yo no sé ustedes, pero el código que se supone es incorrecto... es correcto, y el código que se supone que es correcto... es incorrecto, es decir, si es JavaScript, no puedes poner ";" dentro de los objetos JSON 🤔
Hola! Creo que para ser un Json deberia tener "name" entre comillas. Pero siendo un objeto literal tampoco puede tener punto y coma. Pero aun asi, en ninguno de los dos casos la función retorna '@davidenq'. Además, las comillas que usa son incorrectas.
Según entiendo, así sería la versión correcta:
/** * La funcion getName() devuelve un objeto con la * propiedad Name por lo tanto es necesario * acceder a la propiedad usando * dot notation. * ej: * console.log(getName()); * consologea: {name: "@davidenq"} */ console.log(getName().name); function getName(){ return { name: "@davidenq", }; } //consologea: "@davidenq"
📌 Muchos equipos reciclan sus pruebas unitarias y los toman como código de muestra, eso es una mala idea. El objetivo principal de una prueba unitaria es probar; el único objetivo de un código de muestra es educar al usuario.
¿Qué es exactamente el código de muestra? porque en la lectura me dicen que lo usan los programadores como documentación, pero creo que no se define concretamente.
Tengo la misma duda 🤔
Ademas los ejemplos de codigo y la documentacion debe ser accesible, esto implica un buen uso de Html semantico, y si se usan capturas de pantalla, estas deben tener su altText que transmit la informacion clave.
Ejemplo intermedio: Saludo con función
Lenguaje: JavaScript
<function greet(name) { console.log("Hello, " + name + "!"); } greet("John");>