Aprende a Usar Markdown para Crear Documentos Técnicos
Clase 16 de 20 • Curso de Introducción al Technical Writing y Documentación de Código
Contenido del curso
Markdown es un lenguaje de marcado ligero que muchos profesionales utilizan para crear y editar documentos técnicos. Con Markdown escribes el texto en un editor de texto plano insertando caracteres especiales para crear encabezados, negritas, viñetas, etc. El texto plano es simplemente el alfabeto normal, con unos cuantos símbolos familiares como asteriscos ( * ) o comillas simples ( ``` ). El siguiente ejemplo muestra una descripción técnica sencilla formateada con Markdown:
El sitio web Markdown Tutorial nos comparte que, a diferencia de las aplicaciones de procesadores de texto, el texto escrito en Markdown puede ser fácilmente compartido entre diferentes equipos, dispositivos móviles y personas. Y se está convirtiendo rápidamente en el estándar para escritos de académicos, científicos, escritores y muchas más. Ejemplo de ellos son Platzi, GitHub y Reddit, quienes utilizan Markdown para dar formato a sus comentarios.
¿En qué se utiliza Markdown? 🤓
De acuerdo con la documentación de Markdown, este lenguaje de marcado es bueno para:
- Páginas web
- Contratos
- Notas
- Libros
- Presentaciones
- Emails
- Documentación
- ¡Y muchos más!
Hoy en día muchos escritores técnicos tienen sus blogs, así que cualquiera puede usar Markdown para sus sitios web y blogs.
Editores de Markdown 📋
Para trabajar con Markdown puedes hacerlo desde editores de texto como:
Solo debes crear un archivo con extensión .markdown o .md. Escribe el texto como lo haces habitualmente pero utilizando la sintaxis de Markdown. A continuación, guarda el archivo y, si tu herramienta admite Markdown, impórtalo.
Si quieres un editor online, te recomiendo:
Solo abre el sitio y empieza a escribir. La mayoría de estos editores te muestran dos paneles, uno en donde vas escribiendo y otro en donde se va viendo la adaptación a Markdown.
Breve introducción a la sintaxis de Markdown Ⓜ
Dar formato a textos mediante Markdown tiene una curva de aprendizaje suave. Cabe mencionar que Markdown no hace grandes modificaciones como cambiar el tamaño de la fuente, el color o el tipo. Lo único sobre lo que se puede trabajar es en cómo se muestra el texto, por ejemplo, marcar texto en negrita, crear encabezados u organizar listas de elementos. A continuación, te dejo algunos formatos básicos de introducción al Markdown:
1. Encabezados
Los encabezados se usan frecuentemente en sitios web, artículos de revistas y avisos para llamar la atención sobre una sección. Como su nombre lo indica, actúan como títulos o subtítulos sobre las secciones.
Hay seis tipos de encabezados en tamaños decrecientes y se usa el símbolo hash (**#**) para definir el tamaño del título. Si el encabezado es H1, se agrega un hash, si el encabezado es H2, se agregan dos hashes y así sucesivamente hasta llegar al H6.
# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6
2. Énfasis
Tres básicos elementos en este formato de texto son: itálica, negrita y tachada. Para hacer una palabra en itálica debes poner un asterisco (*) al inicio y al final de cada palabra. Si quieres el formato negrita, serán dos asteriscos (**) al inicio y al final de la palabra o frase. Y si es formato tachado, entonces serán dos virgulillas (~~) al inicio y final de cada palabra o frase.
*Itálica* **Negrita** ~~Tachada~~
Itálica
Negrita
Tachada
3. Listas
Como te mencioné anteriormente, hay varios tipos de listas. Utiliza las listas ordenadas (numeradas) cuando los elementos deban seguir un orden (por ejemplo, instrucciones para cocinar) y las listas desordenadas (con viñetas) cuando no importa el orden de las instrucciones (por ejemplo, una lista de mercado).
- Lista desordenada - Usa este tipo de listas - Cuando no importe el orden - De los elementos de la lista 1. Lista ordenada 2. Aquí los elementos 3. De la lista 4. Debes ir en este orden
4. Enlaces
Este tipo de enlace es el llamado enlace en línea. Para crear un enlace en línea debes encerrar el texto del enlace entre corchetes ( [ ] ) y después encerrar el enlace entre paréntesis ( ( ) ).
[Platzi](https://platzi.com/)
¿Verdad que es muy sencillo?
Si quieres profundizar, aquí está la Sintaxis Básica de Markdown para que te asegures de conocerlo a profundidad. Si lo que quieres es practicar, reserva 20 minutos de tu día a este tutorial de Markdown para aprender toda la sintaxis básica.
Ahora escribe tu documentación con Markdown 👊
Es hora de poner en práctica todo lo que aprendiste en esta clase. ¿Recuerdas la documentación que escribiste en la clase anterior? Ahora debes transformarla a Markdown aprovechando todas las funcionalidades y formatos que acabas de aprender. ¡No olvides dejar tu resultado en los comentarios!
Luego de completar el reto te invito a acompañarme a la siguiente clase para aprender a revisar nuestro contenido efectivamente.