Aprende a destacar en GitHub: Cómo escribir un README que impresione a todos

Repo
Blog / Aprende a destacar en GitHub:… /
Aprende a destacar en GitHub: Cómo escribir un README que impresione a todos

Por: Leonardo Narváez.

En: 19 de Junio de 2023 a las 22:33
Github Portfolio Readme

El README es un elemento fundamental en cualquier repositorio de GitHub. No solo proporciona información importante sobre el proyecto, sino que también es una oportunidad para captar la atención de otros desarrolladores y colaboradores potenciales. Ya que un repositorio detallado es mas fácil de entender de esa forma teniendo mas alcance, aquí te mostraré como estructurar un archivo README.md para tus repositorios.


¿Qué es un Archivo README.md?


Un README es un archivo de texto que se encuentra en la raíz de un repositorio de código, generalmente en plataformas como GitHub. Su propósito es proporcionar información relevante sobre el proyecto a otros desarrolladores y usuarios que visiten el repositorio.


¿Por qué hacer un README.md?


Hacer un README es esencial para presentar tu proyecto de manera clara, brindar instrucciones de instalación y uso, fomentar la colaboración de otros desarrolladores y establecer los derechos de uso del código fuente. Un README bien redactado mejora la experiencia del usuario y aumenta las posibilidades de que tu proyecto sea comprendido, utilizado y mejorado por otros.

Además, hay quienes aprovechan su perfil de GitHub como una especie de portafolio, y en esos casos resulta interesante utilizar los archivos README para realzar la apariencia de sus proyectos, incluso ante posibles reclutadores.


¿Cómo hacer un README?

No se tiene un patrón especifico sobre como hacer estos archivos aunque si se debe tener en cuenta algunos puntos importantes a la hora de hacer tu README, como:

  • Título e imagen de portada;
  • Insignias;
  • Descripción del Proyecto;
  • Estado del proyecto;
  • Instalación del Proyecto;
  • Funcionalidades;
  • Tecnologías utilizadas;
  • Autores;
  • Licencia.


Titulo e Imagen de portada


Al momento de crear tu README aparecerá el nombre del repositorio, pero lo puedes cambiar sin problemas o editar el contenido.

Se puede poner el titulo de varias formas, aquí te dejo ejemplos:

<em> # Su título aquí </em>

Etiqueta markdown:

### Su título aquí

Con html:

<h1 align="center"> Su título aquí </h1>

Recuerde que puedes agregar cualquier tipo de emogi dentro del README

Si quieres agregar una imagen de portada como mi repositorio, es fácil, solo debes arrastrar la imagen desde el explorador hasta el editor de README de github. No olvides poner una imagen llamativa que represente el proyecto o tu perfil de usuario si lo usas como portfolio.


Otra forma de agregar la imagen es alojarla en cualquier servicio de cloud o de cualquier imagen que encuentres en Internet, solo debes seguir la siguiente estructura:

![descripción de la imágen](URL de la imagen)


Insignias


En algunos repositorios, se emplean badges, que en su traducción literal significan placas, emblemas o insignias. Estos badges tienen la finalidad de mostrar el estado actual del proyecto, su licencia (si corresponde), las versiones utilizadas, las dependencias, las pruebas realizadas, entre otros aspectos relevantes.

Si tu quieres usar estos badges te recomiendo echar un ojo a Shields.io, en la pagina principal te muestra ejemplos que puedes pegar directamente en tu repositorio de Github, solo debes copiar el enlace y usarlo dentro de tu README.

Ejemplos:


![GitHub Org's stars](https://img.shields.io/github/stars/leonxrdon?style=social)
![GitHub Org's issues](https://img.shields.io/github/issues/leonxrdon/leonxrdon?style=social)
![GitHub Org's forks](https://img.shields.io/github/forks/leonxrdon/leonxrdon?style=social)

![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?style=plastic&logo=html5&logoColor=white)


Descripción del Proyecto


Dado que el objetivo principal del archivo README es describir el proyecto, es recomendable que incluyas una breve explicación del proyecto junto al título, imagen de portada y/o insignias, en caso de que las haya. Esta breve descripción debe resaltar el objetivo principal de tu proyecto.

Si usas tu README como portfolio usa esta sección para dar una breve descripción sobre ti, a que te dedicas, en que estas trabajando, donde te pueden contactar o también puedes describir o enlistar los proyectos que haz trabajado, usa recursos como imágenes, gifs detallando las funcionalidades.

Ejemplo descripción sobre mí:

Ejemplo de proyectos en los que trabajado: