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:
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.
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:
Ahora que tienes esto claro, vamos al paso a paso para construir el README.
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.
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.
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.
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.
Aprovecha esta sección para contarle al público cuáles son las características más importantes del proyecto, presúmelas.
Si el proyecto requiere alguna instalación específica, cuéntale a tu usuario los pasos que debe seguir para empezar a utilizarlo.
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.
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.
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.
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.
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.
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 💚
¡Excelente Post, como siempre Alex, gracias!
P.D.: haz un post de “5 alternativas a GitHub Copilot”.
¿Alguien más de Platzi estaría interesado?
Ya lo van a empezar a cobrar… 🥺
# h1## h2 ### h3#### h4##### h5###### h6**Bold_text_here***s_text_here* [link_title](https:link_enlace) <imgsrc="" /><palign="center"> text_p </p> //todo....Hola Rodrigo!
Encontré este artículo con la documentación de cada elemento que puedas usar en Markdown
Espero que te ayude para comentar el blog de Alex, Ya quiero ver tus Readme 🙌
Markdown: el lenguaje de estilos para los README.md de tus paquetes npm … ¡ y de los tutoriales de Platzi!
Está muy padre tu aporte Alex ♥
Lo voy a aplicar en ArtStation y en Behance y cuando lo acabe te comparto los links!
Hey Alex me encantó el post, aquí te dejo mi primer repo siguiendo estos pasos. PlatziPunks by @bjvalmaseda 💙
Siguiendo las instrucciones del blog, me quedó algo decente en el readme de mi proyecto git. Poco a poco voy puliendo mi repo :3
Excelente post, muy interesante!
Muy importante el README, toda app profesional debe tener uno completo. Se utiliza siempre en proyectos Open Source, pero he notado poca cultura empresarial de crear un buen README en proyectos privados y dejar documentadas las cosas.
Gracias por compartir, no conocia la importacia de algunos tips mencionados.
muy bien es de mucha utilidad