Documenta tu proyecto con README.md

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 (#).

README TITLE FOR POKEDEX

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í:

README DESCRIPTION FOR POKEDEX

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).

README Installation description

Despliegue / Compilación

Indica cómo podemos preparar el proyecto para producción

README DEPLOY DESCRIPTION

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.

Podekex demo

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á.

Pokedex License MIT

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.

Agradecimientos

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.

Pokedex DEMO 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

Pokedex Badge

¡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:


¡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 😁.

Referencias / Más información