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

Lenguajes de programaci贸n, tipos de datos y estructura de documentos HTML

12/20

Lectura

Recuerda que en la clase 鈥溌縌u茅 es la programaci贸n?鈥 te recomend茅 que tomar谩s el Curso Gratis de Programaci贸n B谩sica y la Carrera de Fundamentos de Programaci贸n para entrar a fondo en todo lo que tiene que ver con el fabuloso mundo de la programaci贸n.

En este curso nos enfocaremos b谩sicamente en crear documentos t茅cnicos, aunque es probable que en tu trayectoria tambi茅n te encuentres con que alg煤n d铆a debas documentar un bloque de c贸digo, una API o un proyecto de software.

Documentar c贸digo es todo un mundo, as铆 que, siendo este un curso de nivel introductorio, te mencionar茅 de manera muy light algunos conceptos b谩sicos de programaci贸n, su definici贸n corta y concisa.

Tipos de datos 馃拋鈥嶁檧锔

Un tipo de dato es la propiedad de un valor que determina su dominio. Es decir, qu茅 valores puede tomar, qu茅 operaciones se le pueden aplicar y c贸mo es representado internamente por la computadora.

Los tipos de datos m谩s comunes son:

  • char o string (textos 鈥溌ola!鈥, 鈥渆sto es un string鈥濃)
  • int (12, 6, 873鈥)
  • double o float (1.5, 8.32, 3.1416鈥)
  • booleano (verdadero o falso)

String 馃敗

El tipo de dato string representa texto. Dependiendo del lenguaje de programaci贸n puedes encerrar ese texto en comillas sencillas (') o comillas dobles ("). Por ejemplo, 鈥楬ello, world!鈥 o 鈥淗ello, world!鈥.

La concatenaci贸n funciona para unir palabras y puedes usar el signo 鈥+鈥 para hacerlo.

Por ejemplo:

  • "Hello" + "World" ser铆a "HelloWorld"

Si lo notas, no hay un espacio entre las palabras, por lo cual, debes agregarlo:

  • "Hello" + " " + "World" o tambi茅n "Hello " + "World".

Para dar un salto de l铆nea debes usar caracteres especiales, en este caso:

  • \n es usado para crear una nueva l铆nea.
  • \t es usado para tabular.

Por ejemplo:

鈥淗ello\nWorld鈥 arrojar铆a como resultado:

Hello

World

Curso de Expresiones Regulares

Int o double 馃挴

Los tipos de datos int o double son n煤meros enteros o decimales. Un n煤mero entero puede ser tu edad o la cantidad de integrantes de tu familia. Un n煤mero decimal puede ser tu peso o el n煤mero de kil贸metros que caminas todos los d铆as.

El tipo de dato importa dependiendo de lo que quieras almacenar, por ejemplo, el n煤mero 7 puede ser tipo de dato entero o puede ser string:

  • int = 7

  • string = "7"

  • 7 + 7 = 14

  • 鈥7鈥 + 鈥7鈥 = 鈥77鈥

Booleano 馃懇鈥嶁殩锔

Los tipos de datos booleanos solo ofrecen dos valores: falso o verdadero. Com煤nmente se representan con ceros y unos o con True o False.

HTML y JavaScript 馃柤

JavaScript es un robusto lenguaje de programaci贸n que puede ser aplicado a un documento HTML y es usado para crear sitios web din谩micos e interactivos. Mientras JavaScript define la funcionalidad e interactividad de los sitios web, HTML (HyperText Markup Language) sirve como est谩ndar de referencia para la codificaci贸n y estructuraci贸n de estos, es est谩tico y no tiene alguna funci贸n como tal.

Cuando escribes c贸digo en HTML est谩s escribiendo etiquetas HTML. Todas las etiquetas HTML est谩n hechas con un n煤mero de partes espec铆ficas, incluyendo:

  • El car谩cter 鈥渕enor que鈥 <.
  • Una palabra o car谩cter que determina qu茅 etiqueta se est谩 escribiendo.
  • Cualquier n煤mero de atributos HTML que se quiera usar, escritos de la forma nombre=鈥漹alor鈥.
  • El car谩cter 鈥渕ayor que鈥 >.

Etiquetas HTML b谩sicas

Hay una serie de etiquetas que son las m谩s usadas para crear cualquier documento HTML:

  • <body> para el contenido.
  • <head> para informaci贸n sobre el documento.
  • <div> divisi贸n dentro del contenido.
  • <a> para enlaces.
  • <strong> para poner el texto en negrita.
  • <br> para saltos de l铆nea.
  • Del <h1> al <h6> para t铆tulos dentro del contenido.
  • <img> para a帽adir im谩genes al documento.
  • <ol> para listas ordenadas, <ul> para listas desordenadas y <li> para elementos dentro de la lista.
  • <p> para par谩grafos.
  • <span> para estilos de una parte del texto.

HTML cuenta con un total de 91 etiquetas. Sin embargo, una etiqueta por s铆 sola a veces no contiene la suficiente informaci贸n para estar completamente definida. Para ello contamos con los atributos: pares de nombre-valor separados por un 鈥=鈥 y escritos en la etiqueta inicial despu茅s del nombre del elemento. El valor puede estar encerrado entre 鈥渃omillas dobles鈥 o 鈥榮imples鈥.

Esta ser铆a la estructura general de una l铆nea de c贸digo en lenguaje HTML:

<tag attribute1="value1" attribute2="value2">content</tag>

O lo que es lo mismo, con un ejemplo:

<a href="http://www.enlace.com" target="_blank">Ejemplo de enlace</a>

Donde:

  • <a> es la etiqueta o tag inicial y </a> la etiqueta de cierre.
  • href y target son los atributos.
  • http://www.enlace.com y _blank son las variables.
  • Ejemplo de enlace es el contenido.

Veamos como ejemplo el famos铆simo "Hello, world!". Este programa se utiliza generalmente para mostrar en un ejemplo sencillo la sintaxis de un lenguaje de programaci贸n y para introducir a los programadores en dicho lenguaje.

Esta es una pieza de c贸digo escrito en JavaScript y HTML.

<!DOCTYPE HTML>
<html>

<body>

  <p>Before the script...</p>

  <script>
    alert( 'Hello, world!' );
  </script>

  <p>...After the script.</p>

</body>

</html>

Las etiquetas de apertura <html> y <body> son las que comienzan la estructura de este programa.

<!DOCTYPE HTML>
<html> <------ Inicio de la etiqueta HTML

<body> <------ Inicio de la etiqueta del body del sitio web

La etiqueta <p> es de inicio de un p谩rrafo y la etiqueta </p> da cierre a ese p谩rrafo. La etiqueta <script> indica que lo que se escriba dentro de ella corresponde al lenguaje de programaci贸n JavaScript, tambi茅n tiene su etiqueta de inicio y etiqueta de cierre.

<p>Before the script...</p> <------ Un p谩rrafo

  <script> <------ Inicio de la etiqueta de JavaScript
    alert( 'Hello, world!' ); <------ Mensaje en formato de alerta que se mostrar谩
  </script> <------ Cierre de la etiqueta de JavaScript 

  <p>...After the script.</p> <------ Otro p谩rrafo

Finalmente, </body> y </html> son las etiquetas de cierre del programa. Si observas, son id茅nticas a las etiquetas con las que se inici贸 a excepci贸n de que tienen un slash ("/") como se帽al de cierre.

</body> <------ Cierre de la etiqueta del body del sitio web

</html> <------ Cierre de la etiqueta HTML

Variables 馃摝

Una variable es como una caja, dentro podemos guardar cosas. Las variables de JavaScript son cajas que solo pueden guardar una cosa a la vez. Se las denomina as铆 porque su contenido puede cambiar en cualquier momento durante el desarrollo del programa, son variables.

Cada variable tiene un nombre, tipo de dato y valor. Algunos ejemplos:

technical-writing5.png

Las variables tienen ciertos lineamientos a seguir dependiendo del lenguaje de programaci贸n en el que est茅n. Los lineamientos m谩s comunes son:

  • Respetar may煤sculas y min煤sculas en caso de que el lenguaje de programaci贸n sea case-sensitive.

  • Agregar al final de la variable un punto y coma (;).

  • Declarar las variables con la palabra var, no es necesario, aunque es recomendable hacerlo. Ejemplo:

    • var id;

    • var apellidoMaterno;

    • var estatusActivo;

  • Contener solo letras, n煤meros, s铆mbolos de peso ($) y guion bajo (_).

Una vez que tienes las variables, puedes asignarles un valor:

  • var id = 56;

  • var apellidoMaterno = "Salazar";

  • var estatusActivo = 1;

Case-sensitive 馃幁

Algo importante en los lenguajes de programaci贸n es que existe el t茅rmino 鈥case-sensitive鈥, que en espa帽ol ser铆a algo as铆 como 鈥渟ensibilidad a las may煤sculas y min煤sculas鈥. La mayor铆a de los lenguajes de programaci贸n son case-sensitive y JavaScript no es la excepci贸n. Esto quiere decir que el programa tiene la capacidad para distinguir entre may煤sculas y min煤sculas.

Para entenderlo mejor, ser铆a algo as铆:


ApellidoPaterno

apellidoPaterno

apellidopaterno

Aunque digan lo mismo son datos diferentes debido a su capitalizaci贸n, es decir, a su uso de may煤sculas y min煤sculas.

Constantes 馃椉

Las constantes son lo contrario a las variables, son datos que no var铆an su contenido durante la ejecuci贸n del programa. Una vez que toma un valor, este se mantendr谩 fijo. Las reglas de su nombre son las mismas que para crear nombres de variable. Al declarar una constante, se usa el prefijo const.

const escuela = "Platzi";

const edadMinima = 18;

Para documentar una constante necesitas:

  • Nombre

  • Tipo

  • Valor

  • Uso

En ciertos programas hay constantes que deben de ser documentadas, por ejemplo, ciertos mensajes que siempre son lo mismo, mensajes de error o de informaci贸n. Esta informaci贸n la obtienes principalmente con el equipo de desarrolladores o pueden estar comentadas directamente en el c贸digo.

Este es un ejemplo de constantes documentadas, estas muestran mensajes de error:

technical-writing6.png

No existe una manera 煤nica de documentar constantes. Sin embargo, las tablas son recomendables para mejor visualizaci贸n de tu lector.

Como technical writer es probable que en alg煤n momento debas documentar bloques de c贸digo o escribir para una audiencia de programadores. As铆 que aprender a leer c贸digo para despu茅s documentarlo te servir谩 mucho para tu carrera como technical writer.

Curso B谩sico de JavaScript


En el pr贸ximo m贸dulo profundizaremos en la documentaci贸n de c贸digo. 隆Te espero en la pr贸xima clase para aprender a documentar una funci贸n!

Aportes 2

Preguntas 0

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸n.

Comparto este v铆deo para complementar lo de Tipos de datos: https://www.youtube.com/watch?v=cC65D2q5f8I

Los lenguajes m谩s recomendados para iniciar en el mundo de la programaci贸n son Python y JavaScript y hay muchos cursos de estos en Platzi. O si quieres aprender lenguajes compilados puedes aprender Java o C++.

Si no sabes programar, el curso de programaci贸n b谩sica debes tomar:
https://platzi.com/cursos/programacion-basica/