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