Un archivo README (que en inglés significa "Léame") es un documento que contiene información descriptiva sobre el contenido de un directorio en el cual se encuentra ubicado. El propósito principal de este archivo es captar la atención del usuario y proporcionar información orientativa crucial sobre los archivos y carpetas que componen el proyecto.
Como regla general, cualquier persona que no esté familiarizada con el contenido de un directorio debe leer el archivo README antes de interactuar con cualquier otro archivo. Aunque el nombre estándar es README, existen variaciones como "Read Me" o "READ.ME". Dependiendo del formato, es común encontrar extensiones como .txt para texto plano o .md para Markdown.
Contenido Típico de un README
Debido a que no existe una estandarización formal, el formato y el contenido varían significativamente. Sin embargo, en los proyectos de software, es habitual incluir los siguientes apartados:
- Instrucciones de configuración: Pasos necesarios para preparar el entorno.
- Guías de instalación: Cómo instalar el software correctamente.
- Instrucciones de operación: Cómo utilizar las funciones del programa.
- Manifiesto de archivos: Una lista detallada de los archivos incluidos en el directorio o archivo comprimido.
- Información de copyright y licencias: Detalles legales sobre el uso y distribución.
- Información de contacto: Datos del autor o distribuidor.
- Lista de errores conocidos: Bugs reportados que aún no han sido solucionados.
- Instrucciones de resolución de problemas: Guías para solucionar fallos comunes.
- Créditos y agradecimientos: Reconocimiento a quienes contribuyeron.
- Registro de cambios (Changelog): Historial de modificaciones, generalmente dirigido a programadores.
- Sección de noticias: Actualizaciones dirigidas a los usuarios finales.
Historia y Evolución
La convención de incluir un archivo README comenzó a mediados de la década de 1970. En el sistema Unix, donde la mayoría de los nombres de archivos estaban en minúsculas, se utilizaba el nombre en mayúsculas para que resaltara y apareciera al principio de las listas ordenadas por ASCII.
Con el tiempo, el software de Macintosh también adoptó esta práctica. En el mundo del software libre y de código abierto, los estándares de codificación de GNU fomentan su uso para proporcionar una visión general del paquete.
El Impacto de la Web y GitHub
Con la llegada de la web como plataforma estándar de distribución, mucha de la información auxiliar se trasladó a sitios web o wikis. No obstante, plataformas como GitHub han revitalizado la importancia del README. Si un repositorio contiene un archivo README en su directorio principal, GitHub lo muestra automáticamente en la página de presentación del repositorio. Actualmente, el formato README.md (Markdown) es el más utilizado debido a su facilidad de lectura y conversión a HTML.
Archivos Relacionados
Además del README, existen otros archivos de metadatos de contenido de directorio que se utilizan siguiendo convenciones similares, aunque sin estándares formales estrictos, basándose a menudo en las normas de GNU Autotools.