En esta entrada vamos de indicar algunos consejos y buenas prácticas que podemos seguir para redactar un buen fichero de README para documentar nuestro proyecto y que cualquiera que acceda a nuestro repositorio público pueda de un vistazo ver en qué consiste nuestro proyecto, que requisitos tiene y qué tiene que hacer para descargarlo, instalarlo y probarlo.

Este fichero es muy util a la hora de compartir nuestro proyecto, distribuirlo e incluso para nosotros mismos si transcurrido un tiempo queremos retomarlo.

Nos hemos basado en esta plantilla.

Estructura

Hay varias formas de estructurar el proyecto, yo voy a plantear una que he visto que se utiliza en bastantes proyectos y me parece interesante con algunas cosillas de cosecha propia.

Cabecera

Aqui vamos a considerar tres partes:

Nombre del proyecto

El título con el nombre de nuestro proyecto que encabecará el readme

# Título del proyecto

Badges

Debajo del título del proyecto se suelen poner badges de interés, hay muchísimos tags, yo voy a mencionar los dos que utilizo ahora mismo.

Mediante los Actions de GitHub podemos realizar desde construcción de Maven, npm, despliegues en Kubernetes, AWS, Azure, etc. Las acciones realizadas por GitHub Action disponen de una étiqueta que podemos incluir aquí que indique si la construcción a ha ido bien o ha dado error, el despliegue los test etc.
Se puede incluir un tag que indique versión o número de descargas.
Encontre enste enlace con una selección de badges en los que se indica la licencia que tiene nuestro repositorio.
Aquí se nos indica cómo crear nuestros propios badges.

Idiomas 🎏

Lo ideal es que por defecto README esté en inglés, pero podemos incluir en alguna otra carpeta, por ejemplo docs, podríamos incluir README-es u otros idiomas. Mediante enlaces podrías hacer que el usuario cambiase el idioma del readme tanto del original por defecto a los que tengamos en esa carpeta docs como viceversa.

Pero ojo, esto hacerlo al final y recordar que cualquier cambio que hagamos en la documentación debe realizarlo en los dos ficheros.

Además recordar que la url de los recursos que tengan ambos readme cambiará.

Descripción del proyecto

Una imagen vale más que mil palabras

Lo comencé a ver cuando empecé a ver plugins de VisualStudio y ya se ve en casi cualquier plugin, esos gif animados mostrando lo que hace tu plugin, aplicación, etc. Es muy sencillo de hacer y queda genial al principio de nuestro proyecto. Si vuestra aplicación es visual y se puede mostrar, podéis hacer un git animado con ScreenToGif de una forma rápida y sencilla e incluirle en la parte superior de la documentación.

En caso de cosas mas abstractas y esquemáticas, se podría poner un esquema, diagrama o algo que muestre un poco de forma visual en qué consiste el proyecto de vuestro repositorio.

Utilizar iconos

Recordad que en la documentación del README.md ademas de texto dispones de un amplio sentido de iconos que permite enriquecer visualmente el documento. Yo los suelo utilizar para los títulos de cada sección. Hacen la lectura del documento un poco mas ámenas.

🚀📋🔧 ⚙️

Introducción, Resumen, `Starting`

Estas instrucciones te permitirán obtener una copia del proyecto en funcionamiento en tu máquina local para propósitos de desarrollo y pruebas.

Pre-requisitos

Todo lo que debe tener previamente aquel que se vaya a clonar nuestro proyecto para ponerlo en marcha. Sistema operativo, aplicaciones, lenguajes de programación, librerías, etc. Hemos de ponernos en el lugar de cualquier usuario que quiera poner en marcha nuestro repositorio.

Esta muy bien si fuese posible indicar además las versiones de cada uno de los pre-requisitos de nuestro proyecto. Así como también estaría bien en caso de que no sea muy trival los pasos que hay que hacer para instalarlos o configurarlos.

Instalación

Aqui indicaremos los pasos comandos que debemos seguir para tener un entorno de desarrollo ejecutándose.

Test

Aquí indicaremos cómo lanzar los distintos tipos de test que tenga nuestro proyecto.

Otras secciones

Se puede incluir notas sobre cómo hacer deploy, enlace a una wiki, agradecimientos, mencionar herramientas o librerías que se han utilizado, incluir la licencia, etc. La plantilla es bastante extensa y completa por lo que podemos ver.