Recursos Esenciales de Markdown para Documentación Efectiva
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.
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?
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.
Ojalá te animes a usar todas estas herramientas para hacer lo que todo desarrollador de software debe hacer ¡Una gran documentación!
extensiones
Markdown All in One
Markdown Preview Mermaid Support
Markdown es un lenguaje de marcado ligero que se utiliza para dar formato a textos de manera fácil y rápida. John Gruber fue su fundador junto con Aaron Swartz en 2004 con el objetivo de que los textos fueran legibles tanto en su forma sin necesidad de formato fuertemente estructurado, Ingenioso!
Es bueno recordar que Markdown eatá presente no solo en plataformas como GitHub, si no también en Reddit, Stack Overflow, y en muchas aplicaciones de escritura y documentación debido a su simplicidad y versatilidad.
A nivel profesional he utilizado bastante esta extensión.
Y utilizando la documentación de mermaid:
Puedes hacer diagramas de secuencia como este:
O de componentes como este:
Pueden probar también las graficas en:
Gracias por el aporte!
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
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!
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.
¿Soy el único que no puede visualizar las imágenes de la presente lección?
Un diagrama Mermaid es una herramienta que permite crear diagramas y gráficos mediante un lenguaje de marcado sencillo. Se utiliza en Markdown para representar visualmente procesos, flujos y relaciones, facilitando la comprensión de información compleja. En el contexto de Git y GitHub, puedes usar Mermaid para ilustrar flujos de trabajo de versiones y ramas, lo cual es muy útil en la documentación de proyectos. Su integración es directa en plataformas que aceptan Markdown, sin necesidad de instalaciones adicionales.
Muy buenas extensiones markdownlint y Markdown Preview Mermaid Support, facilitan muchísimo la generación de documentación cumpliendo estándares y buenas prácticas, ademas de permitir opciones más allá de solo texto, lo cual facilita el entendimiento y permite dinamismo.
Tanto como Markdownlint como Markdown Preview Mermaid Support es maravilloso
Diagrama de secuencia
Diagrama de Git
No olvidar sempre terminar con dos espacios en blanco para evitar ese error.
Gracias, me costo un poco hacerlo funcionar, pero valio la pena.
por ejemplo, cuando uso textos en los notebooks de Google Colab, Markdown combinado con LaTex es muy poderoso
Clase 21 - Documentación en GitHub con Markdown
¿Para qué caso de uso se usa Markdown en la industria Tech?
El caso de uso más conocido es el de creación de documentación de software.
¿Podemos usar Markdown junto con algunas funciones de HTML?
Sí.
¿En dónde podemos aprender a usar Markdown y a practicar con él?
La documentación Oficial
La extensión markdownlint de Visual Studio Code.
Diagramas de Mermaid.
¿Cuál es la opción ideal para comenzar a aprender sobre Markdown?
La documentación oficial.
¿Por qué usar la extensión Markdownlite de VSC es útil para escribir documentación en la industria Tech?
Porque con ella podemos identificar errores tipográficos y de sintaxis en lo que escribimos, además de brindarnos sugerencias para arreglar dichos errores.
¿Para qué nos sirve la Previsualización de Markdown de VSC?
Es una herramienta que nos permite tener una vista previa de cómo se vería nuestro archivo de documentación con lo que hemos escrito.
¿Para qué sirve la herramienta de Diagramas de Mermaid?
Esta herramienta nos permite crear diagramas que pueden sernos útiles a la hora de escribir la documentación de un proyecto de software.
¿En qué caso deberíamos de usar los diagramas de Mermaid?
Representación de flujos de trabajo.
si no te funciona, asegurate de 2 cosas:
instalarlo desde local a ubuntu en vscode.
cerrar y volver a abrir vscode despues de instalar lo nesesario.
Para obtener el listado de los cambios en tu rama, puedes usar el comando git log. Este comando muestra el historial de commits en la rama actual. Si solo deseas ver los cambios sin los detalles del commit, puedes usar git diff para ver las diferencias entre tu rama y otra referencia, como git diff main para comparar con la rama principal.
Además, considera usar git status para tener un resumen de los cambios no confirmados y git diff --cached para ver los cambios que has preparado para el próximo commit.
Clase 21
Casaulemnte ayer estaba probando Mermaid porque queria a atir de un docuemnto que estaba redacto, tener de manera esquematica un mapa mental, enteonces loqu hice fue pasarla a una IA mi documento y decierle que me pasara el codigo, lo pegue en la web de ellos y voilà:
gran herramienta eso de mermaid, no la conocia pero creo que la usare de aqui en adelante
Que buena lectura, Gracias Profesor, Gracias Platzi.
Heyyy, esto esta Muy Bueno.
MD and MerMaid .
Yo habiase oido de estas herramientas tiempo atras, cuando Yo tomaba clases de Algoritmos, DSA , POO y RDB_SQL
Pero No me quise probarlas por 'Lazyness' ps estaba Muy metido en Tress, Heap y Graphs, Yo no quieria gastar mas mente de lo que solia ser esas Estructuras tan Ambstractas y Algoritmos Recursivos ,
sin embargo ahora Yo pienso mejor y todas estas herramientas estan super, especialmente para diagramas ER de una DB o para Arquitecturas de Software.
