¿Cómo crear un README en GitHub?
Recomendaciones para crear un buen README en tus proyectos
Hace algunas semanas estuve buscando en la red información en español sobre el tema, quería encontrar recomendaciones de cómo organizar los README de los proyectos en GitHub y algunas plantillas de ejemplo. En realidad no encontré muchas guías, así que decidí iniciar un repositorio en github con algunas plantillas guía en inglés y español. Adicionalmente realicé una guía básica de MARKDOWN lenguaje usado para escribir dichos archivos.
🚀 Este fue el resultado, el cual seguiré mejorando:
Es importante recordar la buena práctica de documentar nuestros proyectos, tanto a nivel de código por nuestro yo del futuro y por las personas que leen nuestro código, como a nivel del proyecto, con un buen archivo README o una buena Wiki. El archivo README nos permite crear una -tarjeta de presentación- de nuestro proyecto, allí le debemos dar a nuestro lector una muestra general sobre nuestro proyecto.
Inicialmente dividí el archivo en secciones que creo todo archivo README debe tener, al menos parcialmente, si es que aplican, recodermos que el archivo README de un proyecto debe ser corto y conciso y debe ayudar al lector, por lo menos, a conocer tu proyecto e instalarlo en un ambiente local. A mi manera de ver otros apartados de nuestro proyecto como detalles del funcionamiento o del diseño, es mejor detallarlos aparte, ya sea en una Wiki o en un software que permita realizar documentación de software.
Para el archivo README organicé las siguientes secciones, las cuales creo son imprescindibles en la creación de estos:
- Instalación: El objetivo de esta sección es conocer los pre-requisitos del proyecto, cómo clonar el repositorio y las instruccciones de cómo colocar en funcionamiento el proyecto en tu máquina local.
- Documentación: Aquí puedes compartir la documentación adicional del proyecto, por ejemplo un link a una Wiki.
- Versionado: En esta sección puedes colocar un link a tus -release notes- en GitHub.
- Autores: Realiza un listado de todas las personas que participaron en el proyecto y coloca un link a cada uno de sus perfiles.
- Licencia: Si usas en tu proyecto alguna licencia es bueno especificar cual. Por ejemplo: El proyecto es open-source bajo licencia MIT.
- Créditos: En esta sección puedes colocar comentarios adicionales, dar agradecimientos o invitar a tus lectores a que visiten otros de tus proyectos.
Si tienes alguna recomendación o inclusión para este tipo de archivos no dudes en realizarla y enviármela como recomendación en el repositorio. Así podremos crear distintas versiones de este archivo y distintas formas de abordar la organización del mismo.