traducido por I. A.
Los archivos README tienen una larga tradición en los proyectos de software. Originalmente, estos archivos de texto sin formato contenían información sobre la licencia e instrucciones sobre cómo compilar el artefacto correspondiente a partir del código fuente o notas importantes sobre la instalación del programa. No existe ningún estándar real sobre cómo construir un archivo README de este tipo.
Desde que GitHub (adquirida por Microsoft en 2018) inició su marcha triunfal como plataforma de alojamiento de código libre para proyectos de código abierto, existe desde bastante pronto la función de mostrar el archivo README como página de inicio del repositorio. Todo lo que se necesita es crear un simple archivo de texto llamado README.md en el directorio raíz del repositorio.
Para poder estructurar los archivos README de forma más clara, se buscó una posibilidad de formato simple. Rápidamente se eligió la notación markdown porque es fácil de usar y se puede renderizar de forma bastante eficiente. Esto facilita la lectura de las páginas de resumen y permite utilizarlas como documentación del proyecto.
Es posible enlazar varios archivos markdown como documentación del proyecto. Así se crea una especie de mini WIKI que se incluye en el proyecto y también se versiona a través de Git.
El asunto tuvo tanto éxito que soluciones de autoalojamiento como GitLab o la comercial BitBucket también han adoptado esta función.
Ahora, sin embargo, se plantea la cuestión de qué contenido es mejor escribir en un archivo README de este tipo para que también represente un verdadero valor añadido para los forasteros. Con el paso del tiempo, se han establecido los siguientes puntos:
- Breve descripción del proyecto
- Condiciones de uso del código fuente (licencia)
- Cómo utilizar el proyecto (por ejemplo, instrucciones para compilar o cómo integrar la biblioteca en proyectos propios)
- Quiénes son los autores del proyecto y cómo se puede contactar con ellos
- Qué hacer si desea apoyar el proyecto
Mientras tanto, las llamadas insignias (pegatinas) se han hecho muy populares. A menudo hacen referencia a servicios externos, como el servidor gratuito de integración continua TravisCI. Ayudan a evaluar la calidad del proyecto.
También hay varias plantillas para archivos README en GitHub. Sin embargo, tienes que fijarte en las circunstancias reales de tu propio proyecto y juzgar qué información es realmente relevante para los usuarios. Estas plantillas ayudan mucho a averiguar si se ha pasado por alto algún punto.
El hecho de que prácticamente todos los fabricantes de soluciones de servidores de gestión de control de código fuente hayan integrado ya la función de mostrar el archivo README.md como página de inicio del proyecto para el repositorio de código significa que un README.me también es algo útil para los proyectos comerciales.
Aunque la sintaxis para markdown es fácil de aprender, puede ser más conveniente utilizar directamente un editor MARKDOWN para la edición extensiva de este tipo de archivos. Debes asegurarte de que la vista previa también se muestra correctamente y no se ofrece un simple resaltado de sintaxis.
