Aprende Inglés, Programación, AI y Ciberseguridad.

Antes:$249

Currency
$209
Suscríbete

Termina en:

02d

00h

02m

50s

70

Aprende a crear un excelente README para tus proyectos

52121Puntos

hace 2 años

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:

  1. README es el primer archivo que una persona verá cuándo entre a tu proyecto.
  2. Si tienes un buen README, tu proyecto se destacará entre los demás.
  3. 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:

  1. ¿Cuál es tu motivación?
  2. ¿Por qué construiste el proyecto?
  3. ¿Qué problema soluciona?
  4. ¿Qué hace a tu proyecto diferente?
  5. ¿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.

Titulo

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.

Descripcion

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.

contenido

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.

ejemplo

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.

Caracteristicas

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.

instalación

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.

El proceso

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.

Recursos utiles

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.

Licencia

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.

Autores

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 💚

Alex
Alex
alexcamachogz

52121Puntos

hace 2 años

Todas sus entradas
Escribe tu comentario
+ 2
Ordenar por:
4
34262Puntos

¡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… 🥺

2
12871Puntos
<h1>Ayudenme a completar aqui un cheatsheet de markdown</h1>
# h1## h2 ### h3#### h4##### h5###### h6**Bold_text_here***s_text_here*

[link_title](https:link_enlace)

<imgsrc="" /><palign="center"> text_p </p>

//todo....
1
35477Puntos
2 años

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 🙌

1

Está muy padre tu aporte Alex ♥
Lo voy a aplicar en ArtStation y en Behance y cuando lo acabe te comparto los links!

1
3592Puntos

Siguiendo las instrucciones del blog, me quedó algo decente en el readme de mi proyecto git. Poco a poco voy puliendo mi repo :3

1
2494Puntos

Excelente post, muy interesante!

1
70113Puntos

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.

1
1925Puntos

Gracias por compartir, no conocia la importacia de algunos tips mencionados.

1
989Puntos

muy bien es de mucha utilidad