Cursos Empresas Blog Live Conf Eventos Precios

Herramientas útiles para documentación con Markdown

En las clases anteriores has visto la relevancia de trabajar con Markdown y lo mucho que este lenguaje te puede ayudar para crear una gran documentación. En esta clase lo que veremos son algunos de los muchísimos recursos que puedes utilizar para poder escribir de una gran manera utilizando Markdown de la mejor manera posible. ¡Comencemos!

Simplemente, la mejor referencia para conocer todo lo que se puede hacer con Markdown dentro de los documentos, aquí puedes comenzar a leer mucho.

Mi primera sugerencia es irte a la opción de Cheat Sheet, en esta sección podrás encontrar todo lo que puedes hacer, desde la sintaxis básica hasta la extendida. Lo mejor que puedes hacer comenzar a practicar aquí con esto, la verdad es que si sabes usar estas características ya estás dominando el 90% de todo el trabajo.

También considera que Markdown es compatible con algunas funciones de html como </img>, lo que te permitiría jugar un poco más con el diseño de tu documento.

Si tienes un poco más de tiempo libre estaría fenomenal visitar la sección de Get Started en donde el sitio explica como funciona Markdown lo que es una lectura muy buena para aprender un poco más. ¡Dale un vistazo!

Extensión de Markdown para VS Code

Ya que conoces lo que Markdown puede hacer y su sintaxis lo mejor que puedes hacer es instalar la extensión de Markdown dentro de VS Code, esto te puede llevar a un nivel mucho más avanzado de documentación porque te puede ayudar con la estructura del proyecto mostrándote las reglas que es recomendable no dejar en el documento.

Puedes encontrar el enlace de la extensión aquí.

Dentro de VS Code la imagen es como la siguiente:

Una vez que lo hayas instalado entonces es momento de ponerla en prueba y para ello debes simplemente cometer un par de errores al momento de escribir tu documento. Yo lo hice con este que ahora estás leyendo. Podrás ver las líneas amarillas en cada línea por corregir.

¿Quieres lo mejor? Solo basta que te coloques encima de las líneas para que puedas conocer el error que puedes corregir.

Solo es cosa de que veas la regla y la modifiques, te debo confesar que esta extensión me ha hecho aprender a redactar de manera más eficiente mis documentos. ¡Me encantaría recordar quién me la enseñó para poder agradecerle por el gran tip!

Previsualización de Markdown

Dentro de VS Code puedes previsualizar todos los documentos markdown antes de colocarlos en un control de versiones, solo es necesario que te ubiques en la esquina superior derecha para encontrar un ícono con una lupa y que te permite previsualizar el documento.

Al hacerlo podrás ver una división entre el documento que estás editando y su presentación final dándote no solo una vista previa, sino que también podrá mostrar cualquier error como una ruta de imágenes mal direccionada o cosas por el estilo.

Usar esta vista es un recurso que puedes utilizar para muchas opciones, como evitar un commit que repare los errores de uno anterior. Lo importante es que si usas el monitor de una laptop podrá ser un poco complicado y es aquí donde podrás ansiar tener un monitor ultra wide para trabajar con total felicidad (¡yo quiero uno de esos!).

Diagramas Mermaid

Dejando de lado la funcionalidad básica de lo que puedes hacer con los markdown y VS Code podemos dar un paso adelante y utilizar una herramienta que te hará hacer documentos de otro nivel con los diagramas mermaid.

Estos diagramas te permiten diseñar gráficas de muchos niveles y personalizarlas con la complejidad que deseas.

Por ejemplo, gracias a un código similar al siguiente podrás representar el flujo de interacción entre diferentes ramas, muy acorde a nuestro curso ¿no?

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

Al insertar el código en tu documento podrás ver el resultado luciendo como esta imagen.

Hacer diagramas así es muy útil para representar flujos de trabajo de una manera visual y mucho más cómodos de entender, además, una ventaja adicional, es que no se requiere ninguna instalación o configuración adicional, simplemente agregas el diagrama y todo aparece de maravilla.

Para poder jugar más con el código mermaid en tus documentos, lo mejor es visitar el visualizador de diagramas de mermaid aquí.

Ojalá te animes a usar todas estas herramientas para hacer lo que todo desarrollador de software debe hacer ¡Una gran documentación!

Recursos Esenciales de Markdown para Documentación Efectiva

Curso de Git y GitHub

Clase 21 de 42

Clase 21 / 42

Daniel F Lopez

Hace 2 años

Una herramienta que he aprovechado mucho para los READMEs, principalmente de mi perfil es Simple Icons dado que cuenta con logos geniales de lenguajes de programación, software, librerías, empresas, entre otros, con lo cual se pueden importar fácilmente. Y si los usas con los puedes personalizar de una manera muy útil. :O :D

Raul Fernandez

Hace 7 meses

Hola Daniel, muchas gracias por compartir. Nos podrías dar un poco más de contexto, cómo se usan Simple Icons y Shields.io, un ejemplo concreto serviría mucho. Visité a ambas páginas, pero no logro ver cómo nos puede servir. En especial la de Shields.io, no me quedó claro qué hace ni como se usa. Pude hacer uno que otro badge, pero la verdad es que no entendí su utilidad. Muchas gracias!

Daniel F Lopez

Hace 7 meses•editado

Hola Raul

Puedes ver un ejemplo en mi README de GitHub DanielFLopez1620 aunque hay muchos repositorios que usan esta herramienta, así que puedes explorar READMEs base en GitHub y encontrarás varias.

El uso es sencillo Simple Icons es una librería de íconos, de muchas cosas, desde software hasta herramientas de trabajo, que puedes agregar directamente. Shields.io te permite incorporarla en tarjetas y darles formato (color, tamaño...) para que se adapten a un estilo en particular, por ejemplo:

!Python

Para más info, te recomiendo vayas a la docuemntación de los dos sitios, los links estan en el post original.

Comentarios (21)21 comentarios

Gino G. Viloria

Andrés Salomón Enríquez Ochoa

Hace 3 meses

Samuel Steven Bernal Martínez

Mateo Muñoz Bustamante

Hace un año

Yunuen Estrada

Eduardo Alonso Estrada Peraza

Hace 10 meses

Sara María Mejia Sánchez

Yesica Alejandra Giraldo Tique

Ruben Dario Leon Rivera

Martin Vivar

Carlos Ramos

Alfonso Neil Jiménez Casallas

Ariadna Sophia Cabrera Carrera

Edil Guardado

Hace 6 meses

Juan Diego Ussa Aponte

José Lancheros Ayora

Jhon Alexander Mosquera Vanegas

Hace 12 días

Javier Ramos

Hace un mes

Alberto Vanegas Garcia

Carlos Valdez

SANTIAGO ALBERTO BOLIVAR CARDENAS.

Bryan Castano

Recursos Esenciales de Markdown para Documentación Efectiva

Progreso del curso

Fundamentos de Git y control de versiones

Introducción a GitHub

Herramientas de colaboración en GitHub

GitHub Codespaces

Seguridad y buenas prácticas en GitHub

Administración de GitHub

Gestión de Cambios con Pull Requests

GitHub Releases

Cierre