Volver a la página principal
lunes 29 julio 2024
53

Cómo crear un buen archivo README.md

El archivo README es lo primero que un usuario verá al ver tu repositorio. Le da al usuario una idea de qué trata el proyecto, qué lenguaje se usó, cuáles son los términos y condiciones, qué puede hacer tu proyecto, muestra capturas de pantalla de tu aplicación en funcionamiento, etc.

¿Por qué es importante?

Este usuario podría ser un reclutador, tu futuro jefe o cliente. Por lo tanto, es importante que el README de tu proyecto responda al qué, por qué y cómo del proyecto.

Por lo tanto, es crucial incluir la información más importante, dar una descripción clara del proyecto y la tecnología utilizada, y proporcionar enlaces e instrucciones adicionales que no puedan caber en el archivo README para evitar búsquedas innecesarias en todos los demás archivos, lo que podría hacer que el usuario simplemente pierda interés y pase al siguiente posible empleado.

No puedo enfatizar lo suficiente lo importante que es escribir una buena documentación sobre el proyecto. No solo el usuario busca información sobre el proyecto en sí, sino que también ve tus habilidades de documentación y tu atención al detalle, lo que podría acercarte mucho más a conseguir un trabajo.

Si has leído otros artículos míos, probablemente hayas notado lo importante que fue para mi carrera haber aprendido otras habilidades además de la programación que finalmente me ayudaron a conseguir un trabajo. Y una buena documentación fue una de ellas.

¿Qué incluir en un README?

Aquí hay algunas preguntas orientadoras que te ayudarán:

  • ¿De qué trata el proyecto?
  • ¿Por qué lo desarrollaste, cuál fue tu motivación?
  • ¿Qué problema resuelve?
  • ¿Qué has aprendido?
  • ¿Qué hace que tu proyecto se destaque?

Te mostraré cómo convertir estas preguntas en texto.

Posible estructura

Descripción

Propósito y descripción del proyecto para que la persona que lea tu portafolio pueda entender el proyecto en los primeros segundos de leer la información del proyecto.

Tech stack

Pila tecnológica incluyendo los lenguajes de programación, bibliotecas y frameworks que usa tu proyecto (por ejemplo: Python, React, ...). Si tienes una aplicación front-end que usa una API pública externa, por favor menciona esto.

Diseño

Ejemplos de interfaces de usuario asociadas con el proyecto. Si el proyecto tiene una interfaz de usuario, puedes insertar un GIF, video o imagen de la interfaz de usuario.

Si es una aplicación que se ejecuta en la terminal, puedes crear un GIF que muestre cómo trabajar con ella. Esto es bueno para dar una idea de cómo interactuar con la aplicación y qué vería alguien al ejecutar el proyecto.

Características

Si tu proyecto tiene muchas características, deberías agregar una sección de Características y enumerarlas aquí.

Cómo ejecutar el proyecto

Instrucciones sobre cómo configurar, ejecutar y usar el proyecto. Esto es útil si alguien quiere iniciar el proyecto desde cero; deberían encontrar todo lo que necesitan saber en el README del proyecto sin necesitar ayuda de ti.

Si es simple, puedes incluirlo en el archivo README. También puedes referirte a otro archivo en tu proyecto si las instrucciones son más largas.

También deberías alojar tu proyecto, por ejemplo, usando Netlify, para que los usuarios puedan abrir la aplicación desplegada y usarla de inmediato para ver cómo funciona. (Ten en cuenta que no todos los reclutadores que miran tu perfil de GitHub tienen un conocimiento sólido sobre cómo configurar un proyecto localmente).

¿Cómo darle estilo a un README?

La extensión .md en README.md significa Markdown, un lenguaje de marcado ligero con una sintaxis simple para el formato de texto. Es un lenguaje muy simple para crear archivos README hermosos y presentables para GitHub.

Por lo tanto, puedes usar el lenguaje de markdown típico, como:

# Encabezado 1
## Encabezado 2
### Encabezado 3

Énfasis, también conocido como cursiva, con *asteriscos* o _guiones bajos_.

Énfasis fuerte, también conocido como negrita, con **asteriscos** o __guiones bajos__.

Énfasis combinado con **asteriscos y _guiones bajos_**.
1. Primer elemento de lista ordenada
2. Otro elemento
⋅⋅* Sub-lista desordenada.
1. Los números reales no importan, solo que sea un número
⋅⋅1. Sub-lista ordenada
4. Y otro elemento.

[Soy un enlace en línea](https://www.google.com)

[Soy un enlace en línea con título](https://www.google.com "Página principal de Google")

![texto alternativo descriptivo](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Título del logo 1")

y mucho más. Asegúrate de aprovecharlo al máximo.

Etiquetas:
proyectos
Compartir:
Creado por:
Author photo

Jorge García

Fullstack developer