Guía profesional sobre README

Un perfil de GitHub pulido es una parte importante de su identidad pública como desarrollador. ¿Por qué? Por un lado, lo más probable es que sea el primer lugar en el que los empleadores potenciales busquen evaluar sus habilidades y profesionalismo. Además, le permite conectarse y mostrar su trabajo a otros desarrolladores, lo que puede conducir a colaboraciones interesantes.

Un componente clave de su perfil, y uno que muchos desarrolladores nuevos pasan por alto, es el archivo README asociado con cada repositorio. Un archivo README actúa como un escaparate virtual en un repositorio, es lo primero que una persona ve cuando visita un repositorio en GitHub. Pero también es mucho más que eso: Los archivos README contienen información esencial sobre el proyecto del repositorio. Por lo tanto, la calidad de un archivo README puede marcar la diferencia entre un repositorio de alta calidad y uno de baja calidad.

No existe una manera correcta de estructurar un archivo README. Sin embargo, hay una forma muy incorrecta y eso es no incluir un README en absoluto o crear uno muy pobre.

Para ayudarlo a crear archivos README de alta calidad desde el principio, esta guía describe algunas de las mejores prácticas básicas para crearlos. A medida que avance en su carrera profesional, desarrollará sus propias ideas sobre lo que hace que un archivo README sea efectivo.

¿Qué debería incluir un README de alta calidad?

Un archivo README de alta calidad explica qué hace su aplicación y por qué utilizó las tecnologías que utilizó. Como mínimo, un README necesita un título y una breve descripción que explique el qué, el por qué y el cómo del proyecto.

Utilice las siguientes preguntas como guía:

• ¿Cuál fue su motivación?
• ¿Por qué desarrolló este proyecto? (Nota: La respuesta no es “Porque fue una asignación de tarea”.)
• ¿Qué problema resuelve?
• ¿Qué aprendió?
• ¿Qué hace que su proyecto se destaque?

Su README también podría describir algunos de los desafíos que enfrentó, así como las funciones que planea implementar en el futuro. Además, si su proyecto está implementado, asegúrese de incluir un enlace a la aplicación implementada para que la gente pueda verlo en acción.

¿Cómo creo un archivo README de alta calidad?

Los archivos README se escriben en Markdown y siempre se nombran README.md (tenga en cuenta que README está todo en mayúsculas). Si es nuevo en Markdown, consulte la guía de GitHub sobre cómo dominar Markdown o busque tutoriales sobre Markdown en Internet.

Para obtener un excelente ejemplo de un archivo README de alta calidad, visite el repositorio en VS Code de Microsoft.

Plantilla de README profesional

Hemos proporcionado una plantilla flexible para usar como punto de partida, pero no dude en adaptar su archivo README para que se ajuste a las necesidades particulares de su proyecto.

Utilice la siguiente plantilla de Markdown para crear un archivo README profesional:

# <Your-Project-Title>

## Descripción

Proporcione una breve descripción que explique el qué, el por qué y el cómo de su proyecto. Utilice las siguientes preguntas como guía:

- ¿Cuál fue su motivación?
- ¿Por qué desarrolló este proyecto? (Nota: La respuesta no es “Porque fue una asignación de tarea”.)
- ¿Qué problema resuelve?
- ¿Qué aprendió?

## Índice (opcional)

Si su README es extenso, agregue un índice para facilitar que los usuarios encuentren lo que necesitan.

- [Instalación](#instalación)
- [Uso](#uso)
- [Créditos](#créditos)
- [Licencia](#licencia)

## Instalación

¿Cuáles son los pasos necesarios para instalar su proyecto? Proporcione una descripción paso a paso de cómo poner en funcionamiento el entorno de desarrollo.

## Uso

Proporcione instrucciones y ejemplos de uso. Incluya capturas de pantalla según sea necesario.

Para agregar una captura de pantalla, cree una carpeta `assets/images` en su repositorio y cargue la captura de pantalla en ella. Luego, con la ruta relativa, agréguela a su README utilizando la siguiente sintaxis:

    ```md
    ![alt text](assets/images/screenshot.png)
    ```

## Crédito

Enumere sus colaboradores, si los hubiera, con enlaces a sus perfiles de GitHub.

Si utilizó activos de terceros que requieren autoría, enumere los creadores con enlaces a su presencia web principal en esta sección.

Si siguió tutoriales, también incluya enlaces a ellos aquí.

## Licencia

La última sección de un archivo README de alta calidad es la licencia. Esto permite que otros desarrolladores sepan lo que pueden y no pueden hacer con su proyecto. Si necesita ayuda para elegir una licencia, consulte [https://choosealicense.com/](https://choosealicense.com/).

---

🏆 Las secciones anteriores son lo mínimo indispensable y su proyecto determinará finalmente el contenido de este documento. También puede considerar agregar las siguientes secciones.

## Insignias

![badmath](https://img.shields.io/github/languages/top/nielsenjared/badmath)

Las insignias en sí mismas no son necesarias, pero demuestran un crédito callejero. Las insignias permiten a otros desarrolladores saber que usted sabe lo que está haciendo. Eche un vistazo a las insignias presentadas por [shields.io](https://shields.io/). Es posible que no comprenda lo que todas ellas representan ahora, pero lo comprenderá con el tiempo.

## Funciones

Si su proyecto tiene muchas funciones, enumérelas aquí.

## Cómo contribuir

Si creó una aplicación o paquete, y desea que otros desarrolladores contribuyan con ella, puede incluir directrices sobre cómo hacerlo. El [Pacto de colaboradores](https://www.contributor-covenant.org/) es un estándar de la industria, pero siempre puede redactar el suyo si lo prefiere.

## Pruebas

Vaya un paso más allá y escriba pruebas para su aplicación. Luego, proporcione ejemplos sobre cómo ejecutarlas aquí.

Un perfil de GitHub con archivos README de alta calidad de manera constante seguramente lo ayudará a destacarse entre la multitud de desarrolladores que exponen sus trabajos en GitHub, así que asegúrese de dedicarles a estos archivos importantes el tiempo y la atención que se merecen.

This page was updated 6 months ago
© 2022 edX Boot Camps LLC. Confidential and Proprietary. All Rights Reserved.

Category: github

Tagged under: github, guide,