Documenta tu proyecto con README.md
Todos queremos escribir un buen README, pero si eres como yo, seguramente te quedas en blanco sin saber por dónde empezar. Por eso acá te describiré las secciones más comunes y preguntas que debe resolver esta primera vista a tu proyecto.
¿Qué es un README.md?
Este archivo es la carta de presentación de nuestro proyecto. Generalmente está en la carpeta root del repositorio y contiene la información necesaria para conocer de qué van nuestros archivos e intrucciones para usarlos.
¿Por qué es importante?
Imagina que resolviste una necesidad actual. El código te quedó bien bonito, una buena estructura, buenas practicas, pero... eso no es lo primero que vemos los demás, ¿o sí? Cuando entramos a un repo sin README, lo más seguro es que pasemos de largo, ya que no tenemos claro qué hacer con lo que tenemos en frente. ¡No pudimos deleitarnos con esa función O(n) que te costó tanto codear!
Markdown
Lo primero que debemos saber es cómo escribir archivos en markdown (md), ya que esa es la extensión que usaremos. Hace tiempo hice un editor sencillo que puedes usar para ver en tiempo real el resultado. También te recomiendo entrar en este post que te enseña la sintaxis del lenguaje.
Secciones
Ahora sí, vamos a lo sustancial. ¿Qué secciones deben ser un must en cualquier README? Para esto, construiremos uno juntos basándonos en el proyecto: Pokedex.
Título
El nombre de proyecto. Lo más recomendable es que uses el título de mayor orden en markdown (#).
Descripción
Esta sección debe ser breve, pero también responder la siguiente pregunta
¿Qué problema resuelve mi proyecto?
Nos va quedando algo así:
Instalación
Describe paso a paso lo necesario para instalar y correr tu proyecto. Apóyate en el uso de bloques de código de markdown (``). También le puedes llamar "Comenzando" (o "Getting Started" en inglés).
Despliegue / Compilación
Indica cómo podemos preparar el proyecto para producción
Uso
Si tienes un API, puedes dar ejemplo de su uso en esta sección. En el caso de estudio (Pokedex) no vamos a incluir esta sección.
Demo
Expone un link al live demo de tu proyecto. Puedes usar Github Pages o Netlify para desplegarlo. Agrégalo como una sección nueva o debajo de la descripción.
Licencia
Es muy importante que protejas tu trabajo con una licencia. En este caso usaremos MIT, que es de Open Source, puedes leer más acá.
Contribuciones
Detalla cómo los demás pueden contribuir a tu proyecto.
Pruebas
Si usas pruebas unitarias, puedes explicar cómo correrlas. Generalmente lo hacemos con npm test.
Bonus: Gratitud / Motivación
Es opcional, pero siempre es bonito dar las gracias.
ProTips
¡Usa Emojis! ✨
Esto le dará más vida a tu readme, haciéndolo más sencillo de seguir.
Los divisores son nuestros amigos
Nos ayudan a tener más organizada la información. En markdown los puedes agregar con (---).
Apóyate con imágenes
Que no sea necesario clonar el proyecto para tener una idea de cómo se ve. Apóyate con imágenes o con gif. Puedes usar recordit para grabar un pequeño extracto de tu funcionalidad y agregarlo como gif.
Badges
Visualmente puedes informar el estado de tu proyecto, qué tecnología ocupas o la versión actual, mediante badges. Para este fin te recomiendo que hagas tus badges en shields.io
¡Ya tenemos listo nuestro README! Puedes ver el resultado final acá: https://github.com/musenberg404/pokedex
Plantillas
De igual manera, te dejo un par de plantillas por las que te puedes guiar:
- https://github.com/anabelisam/readme.md
- https://gist.github.com/Villanuevand/6386899f70346d4580c723232524d35a
¡Listo! Tienes las herramientas necesarias para tener un README de lujo, tal como lo merece tu código.
Puedes comentar acá abajo si consideras que me faltó alguna sección o si te fue útil la información 😁.