~ 3 min read

Las claves de un readme poderoso en Github

Si estás construyendo el portafolio de tus proyectos en un repositorio es importante que tengas en cuenta que la portada lo va a decir casi todo a primera vista porque es donde le cuentas al visitante qué va a encontrar allí, cómo usar tus recursos y hasta podría decir un poco sobre tus habilidades blandas 😱.

En los repositorios casi siempre existe un archivo llamado readme.md que traduce “léeme” y su propósito es dar contexto sobre lo que hay allí antes de navegar entre directorios o descargar el código.

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.

💡 El primer paso es el contenido

Lo primero que debes pensar es en la estructura del contenido que quieres mostrar, debe estar ordenada y con una secuencia para hacer más fácil la navegación por el resto de documentos, lo que vas a transmitir y el cómo lo vas a transmitir es muy importante.

🖼 Inserta sólo las imágenes que sean necesarias

Cuando insertas una imagen en formato markdown por default se adaptan al 100% del ancho del documento si son muy grandes, intenta agregar imágenes con tamaños controlados que no se tornen invasivas visualmente en el documento.

📚 Puntual y concreto

Controla la longitud del archivo en cuanto a texto, no escribas un gran libro pues recuerda que es solo un pequeño manual de uso y contexto de lo que está dentro del repositorio. Para documentaciones más completas y detalladas te recomiendo que lo hagas en Gitbook y luego lo cites.

⚙️ ¿Cómo hago funcionar este proyecto?

No olvides explicar cómo ejecutar el código de tu proyecto, no asumas que todas las personas saben qué hacer al descargarlo, especialmente si requiere instalar o actualizar algunas dependencias.

⛲️ Complementa con fuentes o citas

Agregar las fuentes de información de donde te basaste para construir el proyecto, en caso que no aplique puedes citar aquellos sitios que pueden complementar tu contenido.

🅰️ Formato de contenido

Haz buen uso de los titulos, subtitulos, subrayados, negritas y cursivas. Si defines un formato estándar llamarás más la atención. Es recomendable que el texto esté en inglés, también es buena idea tener traducción inglés/español.


Puedes ver un ejemplo de un readme.md sencillo, práctico y limpio en un proyecto que he creado especialmente para este blog post aquí.


Versión anterior de este blog post en 2019

En el ejemplo que vas a encontrar en este proyecto he utilizado las partes básicas que debe llevar tu readme:

  • El primer título es el nombre de tu proyecto.
  • El texto siguiente es una descripción simple y corta del contexto de tu proyecto.
  • Agrega un link a un demo con el proyecto desplegado.
  • Si es requerido, agrega una lista con los pasos mínimos que se necesitan para clonar el proyecto y echarlo a andar en local.
  • Explica qué debe ejecutarse para que sea posible instalarlo o instalar dependencias necesarias.
  • 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.
  • Finaliza con notas o apuntes que quisieras agregar, citando fuentes o dando agradecimientos a las personas que aportaron al proyecto que muestras.
Aprende qué información agregar en tu readme y cómo presentarla.