GitHub es la red social que cualquier persona que se dedique al desarrollo de software debería tener. No solo te permite llevar un control de versiones de tus proyectos, también hace posible mostrarlos a todo el mundo.
Si lo que buscas es hacer visibles tus proyectos, ya sea porque creaste una librería que resuelve los problemas de todo el mundo o estás nutriendo tu portafolio, debes prestar atención a README, ya que:
- README es el primer archivo que una persona verá cuándo entre a tu proyecto.
- Si tienes un buen README, tu proyecto se destacará entre los demás.
- Ayudará a las personas que revisen tu proyecto a entender cómo fue construido y porqué.
Es por ello que en esta ocasión te daré los mejores trucos y tips para que tus README sean la envidia de tus compañeros.
¿Cómo empezar?
Primero, es importante tener en cuenta que cuando escribas el README de tu proyecto, debes responder el qué, el por qué y el cómo del proyecto. Para poder contestar a estos interrogantes puedes preguntarte lo siguiente:
- ¿Cuál es tu motivación?
- ¿Por qué construiste el proyecto?
- ¿Qué problema soluciona?
- ¿Qué hace a tu proyecto diferente?
- ¿Qué aprendiste?
Ahora que tienes esto claro, vamos al paso a paso para construir el README.
¿Qué incluir en el README?
1. Cuéntale al mundo cómo se llama tu proyecto
Esto puede parecer un poco obvio, pero es relevante, ya que el título describe el proyecto entero en una sola frase y puede ayudar a otras personas a entender de qué se trata tu proyecto.
2. Describe el proyecto de forma breve y concisa
La descripción ayuda a profundizar en el objetivo de tu proyecto, debido a que te permite explicar el impactó, por qué utilizaste ciertas tecnologías en su desarrollo, los desafíos a los que te enfrentaste y también contar qué características quieres implementar en un futuro.
3. Incluye una tabla de contenidos
La tabla de contenidos no es obligatoria, pero es una buena idea incluirla si tu README es muy extenso. El principal objetivo al incluir este recurso es ayudar a los lectores a navegar con mayor facilidad entre las diferentes secciones.
4. Muestra ejemplos del proyecto
Enseña tu proyecto, puedes usar capturas de pantalla, imágenes y hasta gifs para ilustrar cómo se ve y sus funcionalidades. Además, si tu proyecto está desplegado en algún servidor, comparte la URL para que las personas que te lean vayan a probarlo.
5. Habla sobre las características principales
Aprovecha esta sección para contarle al público cuáles son las características más importantes del proyecto, presúmelas.
6. Muestra cómo instalar y ejecutar el proyecto
Si el proyecto requiere alguna instalación específica, cuéntale a tu usuario los pasos que debe seguir para empezar a utilizarlo.
7. Cuenta un poco sobre cómo lo creaste
En esta sección puedes incluir las tecnologías con las cuales construiste tu proyecto y también puedes mostrar algunas porciones de código que consideres valiosas para compartir.
8. Incluye algunos recursos útiles
Tan simple como eso, si en el proceso descubriste cierta documentación que te fue útil, inclúyela, así como alguna herramienta que hizo tu trabajo más sencillo. Es posible que la persona que te lea también pueda sacar provecho.
9. Añade una licencia
Si tu proyecto es OpenSource es muy importante que agregues una licencia, esto le ayudará a las personas a conocer los límites de uso de tu código.
Es posible que a la hora de escoger una licencia te puedas sentir un poco perdida, no te preocupes. GitHub creó una herramienta llamada Choose an open source license para ayudarte en estos casos. Si me lo preguntas… es el mejor nombre que le pudieron poner.
10. Reconoce a los autores
Otorga crédito a las personas involucradas en el desarrollo del proyecto. Si trabajaste sola, incluye tu propio crédito; si fue construido en colaboración con más personas, incluye una sección de contribuidores.
Bonus: el resultado
Para ver en detalle cuál es el resultado de un README, aplicando todos estos consejos, puedes visitar el proyecto en el que me basé para todas las imágenes de este blog.
Es tu turno de poner en práctica lo aprendido
Sigue todas las recomendaciones que te compartí en este blog y aprovecha el espacio para hablar sobre tu proyecto y decirle al mundo lo genial que has construido.
No olvides compartirme en los comentarios cómo mejoraste los README de tus proyectos. Yo estaré encantada de echarles un ojo para conocer lo que has creado y, seguramente, el resto de nuestra comunidad también.
Por último, déjame recomendarte el Curso Profesional de Git y GitHub, que va muy de la mano con este blog y con el cual conocerás más sobre Git y Github para alcanzar un nivel envidiable.
No lo olvides, nunca pares de aprender 💚
Curso Profesional de Git y GitHub
