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

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

7

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

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

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

14/20

Lectura

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.

...

Regístrate o inicia sesión para leer el resto del contenido.

Aportes 6

Preguntas 1

Ordenar por:

¿Quieres ver más aportes, preguntas y respuestas de la comunidad?

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

Cosas como if no es necesario explicarlo, pero qué hace cada función y la explicación de líneas más complejas si llevan su comentario

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

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 😃

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 🤔

📌 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.

Ejemplo intermedio: Saludo con función

Lenguaje: JavaScript

<function greet(name) {
    console.log("Hello, " + name + "!");
}

greet("John");>