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:
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:
  
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:
Estado del Proyecto
Si decides no utilizar insignias para indicar el estado del proyecto, resulta útil incluir esta información dentro del texto del README. Aquí tienes un ejemplo:
:construction: Proyecto en construcción :construction:
Resultado:
Si quieres saber como agregar más en este Gist, hay una gran variedad de emojis que puedes usar dentro de tu README.
Instalación del Proyecto
Es importante facilitar a los usuarios como se debe instalar o como empezar a usar tu proyecto, puedes usar una simple descripción de como instalarlo como muestra el siguiente ejemplo , si la instalación es complicada usa recursos como imágenes o gifs.
Ejemplo:
Funcionalidades
En esta sección puedes detallar como usar alguna funcionalidad en especifico, mostrar la estructura que necesita el usuario para que el proyecto funcione adecuadamente, si la funcionalidad es compleja no olvides que puedes usar recursos como imágenes o gifs, dentro de esta sección también puedes enlistar las funcionalidades que tiene tu proyecto.
Ejemplo:
Tecnologías Usadas
Es crucial proporcionar detalles sobre las tecnologías que utilizas en tu proyecto, esto demuestra los conocimientos que has aplicado. Puedes hacerlo mediante una lista o mediante el uso de insignias (badges), lo cual ayuda a resaltar estas tecnologías de manera visual.
Ejemplo:
Autores
También puedes agregar tu foto como autor, usando tu foto de perfil de GitHub y el nombre que hayas registrado, así será mas fácil que se pongan en contacto contigo por cualquier contribución, problema o inquietud.
## Autores | [<img src="https://avatars.githubusercontent.com/u/99487654?v=4" width=115><br><sub>Leonardo Narvaez</sub>](https://github.com/leonxrdon) | | :---: |
Si quieres agregar mas autores usa la siguiente estructura:
| [<img src="url avatar perfil 1" width=115><br><sub>Nombre 1</sub>](url perfil 1) | [<img src="url avatar perfil 2" width=115><br><sub>Nombre 2</sub>](url perfil 2) | [<img src="url avatar perfil 3" width=115><br><sub>Nombre 3</sub>](url perfil 3) | | :---: | :---: | :---: |
Licencia
Por lo general, los repositorios públicos en GitHub se utilizan para compartir software de código abierto. No obstante, para que un repositorio sea considerado realmente de código abierto, es necesario obtener una licencia que permita a otros usuarios tener la libertad de utilizar, modificar y distribuir dicho software.
Ahora que has aprendido cómo crear un README efectivo para tu repositorio en GitHub, es hora de poner en práctica tus conocimientos y animarte a crear el tuyo. Recuerda que un README bien estructurado, informativo y atractivo puede marcar la diferencia al presentar tu proyecto a la comunidad de desarrollo.
