Cómo hacer un "readme" exitoso

Cómo hacer un "readme" exitoso

Si estás en este mundo de la tecnología y andas armando un portafolio de todos tus grandes proyectos y aprendizajes en un repositorio, es importante que tengas en cuenta que la portada lo va a decir casi todo, pues es donde le cuentas al visitante que va a encontrar, cómo usarlo y hasta qué clase de persona eres.

Para esto, están los archivos readme.md, que traduce "léeme" y es justamente para que lo leas antes de entrar a ver código que quizás no vayas a entender sin un contexto.

Este readme está generalmente en la raíz de la carpeta del proyecto y su extensión es .md quiere decir que está en formato "markdown". Este formato te ofrece las principales herramientas para darle una presentación muy limpia a tus archivos.

Vamos a armar un readme.md para un proyecto que contiene mucho código y no tienes ni idea cómo explicarle al visitante por dónde empezar a verlo sin que se confunda y se estrese.

Lo primero que debes pensar es en la estructura del contenido que quieres mostrar, si bien vamos a ver partes del formato markdown, lo que vas a transmitir y el cómo lo vas a transmitir es muy importante.

Aquí puedes ver algunos consejos bien puntuales para que tu readme.md no sea el fantasma que saque corriendo a tus visitantes y que por el contrario te den muchas estrellitas: https://anabelisa.co/tips-para-hacer-un-buen-readme-md/

En el ejemplo que vas a encontrar en este proyecto https://github.com/anabelisam/readme.md he utilizado las partes básicas que debe llevar tu readme:

  1. El primer título es el nombre de tu proyecto.
  2. El texto siguiente es una descripción simple y corta del contexto de tu proyecto.
  3. Agrega un link a un demo con el proyecto desplegado.
  4. Si es requerido, agrega una lista con los pasos mínimos que se necesitan para clonar exitosamente el proyecto y echarlo a andar en local.
  5. Explica qué debe ejecutarse para que sea posible instalarlo o instalar dependencias necesarias.
  6. Se amable y agrega una imagen que indique cómo debe verse el proyecto luego de instalarse o un una vista previa de lo que estás presentando en código. Esta imagen puede estar dentro del mismo proyecto y de preferencia debería estar allí.
  7. Finaliza con notas o apuntes que quisieras agregar, citando fuentes o dando agradecimientos a las personas que aportaron al proyecto que muestras.
  8. Por favor muéstrame tus grandes readme's! Dedícales tiempo y diviértete haciéndolos, es como el landing de tu proyecto. Dale amorcito desde el corazón.

Recuerda que todos los proyectos de mi github te pueden servir de guía con sus portadas porque cada una dice lo que debe decir según el contenido y el contexto.