Readme: el propio nombre, léeme, indica su propósito: ser leído. El archivo readme es el primer archivo que un de­sa­rro­lla­dor debe mirar antes de em­ba­r­car­se en un proyecto, por lo que también es esencial saber cómo escribir un buen archivo readme, para que toda la in­fo­r­ma­ción relevante se presente de forma compacta.

¿Qué es un archivo readme, y para qué sirve?

Los archivos readme, a menudo creados como readme.txt o readme.md, suelen contener in­fo­r­ma­ción im­po­r­ta­n­te sobre el sistema, proyecto o software al que se refieren. Para que los usuarios puedan encontrar fá­ci­l­me­n­te el archivo de un vistazo, se re­co­mie­n­da ubicarlo en el nivel superior del di­re­c­to­rio.

Consejo

En general, en el nombre del archivo se escribe README en ma­yú­s­cu­las. De este modo, los sistemas que di­fe­re­n­cian entre ma­yú­s­cu­las y mi­nú­s­cu­las listarán el archivo antes que todos los demás archivos que empiezan con mi­nú­s­cu­las.

El archivo tiene también distintos pro­pó­si­tos para los distintos tipos de usuarios:

  • Para el usuario final, los archivos readme aclaran posibles preguntas sobre la in­s­ta­la­ción, ac­tua­li­za­ción o uti­li­za­ción de un software.
  • Un archivo readme ofrece varias ventajas para tu propia labor de de­sa­rro­llo. Por un lado, antes de empezar con el de­sa­rro­llo pro­pia­me­n­te dicho, el archivo readme puede servir de guía para la ejecución del proyecto. Por otro lado, también ayuda a ponerse de nuevo al día si un proyecto queda en pausa durante un largo periodo de tiempo.
  • Para otros de­sa­rro­lla­do­res, los archivos readme explican el código y pro­po­r­cio­nan in­fo­r­ma­ción im­po­r­ta­n­te sobre su de­sa­rro­llo posterior o sobre cómo utilizar un sistema, un software o proyectos de código abierto.

¿Qué debería contener un archivo readme?

De­pe­n­die­n­do de su propósito, un archivo readme puede ofrecer los si­guie­n­tes co­n­te­ni­dos:

  • Una de­s­cri­p­ción general del sistema o proyecto.
  • El estado del proyecto, que es pa­r­ti­cu­la­r­me­n­te im­po­r­ta­n­te si el proyecto está todavía en de­sa­rro­llo. En él se mencionan los cambios planeados y la dirección de de­sa­rro­llo del proyecto, y se es­pe­ci­fi­ca di­re­c­ta­me­n­te si un proyecto está terminado.
  • Los re­qui­si­tos del entorno de de­sa­rro­llo para la in­te­gra­ción.
  • Una guía para la in­s­ta­la­ción y el fu­n­cio­na­mie­n­to.
  • Una lista de las te­c­no­lo­gías uti­li­za­das y, cuando proceda, enlaces con más in­fo­r­ma­ción.
  • Los proyectos de código abierto que se pueden modificar o de­sa­rro­llar deben incluir una sección de co­la­bo­ra­ción deseada en el archivo readme.md: ¿cómo se so­lu­cio­nan los problemas? ¿Cómo deberían los de­sa­rro­lla­do­res impulsar los cambios?
  • Bugs conocidos y posibles co­rre­c­cio­nes de errores.
  • Sección de preguntas fre­cue­n­tes con todas las preguntas pla­n­tea­das hasta la fecha.
  • In­fo­r­ma­ción sobre derechos de autor y licencias.

Es im­po­r­ta­n­te escribir siempre el readme en un lenguaje apropiado para el usuario final. Solo así se pueden aclarar la mayoría de las preguntas.

Posibles formatos de archivo readme

Puedes escribir y guardar un archivo readme en cualquier formato de archivo de texto. Los formatos van desde readme.txt a readme.doc y readme.1st. De­pe­n­die­n­do de la pla­ta­fo­r­ma en la que se vaya a ejecutar el software, el formato del archivo se adapta al sistema en cuestión y a su programa de vi­sua­li­za­ción de texto. Así se garantiza que el programa de texto pueda leer el archivo.

Hoy en día, los de­sa­rro­lla­do­res usan ge­ne­ra­l­me­n­te el formato readme.md, pero qué es un archivo .md. La extensión de archivo indica que es un archivo readme en formato Markdown. Markdown convierte el texto a HTML con ayuda de ca­ra­c­te­res de formateo. Un archivo readme co­rre­c­ta­me­n­te formado y es­tru­c­tu­ra­do ofrece a los usuarios un resumen completo del proyecto.

Readme.md: ejemplo en formato Markdown

Aquí te mostramos cada uno de los elementos es­tru­c­tu­ra­les de un archivo readme.md así como las po­si­bi­li­da­des que ofrece el formato Markdown. Para permitir la co­la­bo­ra­ción en todo el mundo y evitar barreras li­n­güí­s­ti­cas, el archivo readme siempre debe estar en inglés.

Ejemplo de readme en formato Markdown:

# Project name
***
Short Description about the project.
Consejo

Con tres as­te­ri­s­cos (***) puedes insertar una línea de se­pa­ra­ción ho­ri­zo­n­tal.

Arriba del todo, en el archivo readme, se incluye un nombre de proyecto si­g­ni­fi­ca­ti­vo y una breve ex­pli­ca­ción sobre el tipo de proyecto. En Markdown, la al­moha­di­lla (#) siempre introduce un en­ca­be­za­do. El número de al­moha­di­llas determina el tipo de en­ca­be­za­do:

# Headline H1
## Headline H2
### Headline H3
#### Headline H4 
##### Headline H5
###### Headline H6

Si la do­cu­me­n­ta­ción es extensa, un índice claro pro­po­r­cio­na una buena visión general:

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)

El índice de contenido de readme.md puede es­tru­c­tu­rar­se fá­ci­l­me­n­te con una lista ordenada. Basta con insertar el número que co­rre­s­po­n­da al principio de la línea para crear la lista.

GitHub añade au­to­má­ti­ca­me­n­te ide­n­ti­fi­ca­cio­nes a los en­ca­be­za­dos del archivo readme. Las ide­n­ti­fi­ca­cio­nes se generan a partir del nombre del en­ca­be­za­do, y los guiones (-) re­em­pla­zan los espacios. Son ex­ce­le­n­tes para la na­ve­ga­ción de anclaje del índice de contenido. Si el archivo readme.md pretende usarse en otra pla­ta­fo­r­ma que no asigne au­to­má­ti­ca­me­n­te ide­n­ti­fi­ca­cio­nes a los en­ca­be­za­dos, la na­ve­ga­ción de anclaje se puede generar mediante HTML:

## Table of Contents
<a name="general-info"></a>
### General Info

El índice va seguido de los bloques de contenido re­s­pe­c­ti­vos de las secciones in­di­vi­dua­les:

## General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](/path/to/the/screenshot.png)

La in­fo­r­ma­ción general del proyecto es im­po­r­ta­n­te para hacerse una idea de este más allá de la breve ex­pli­ca­ción. Markdown permite también insertar gráficos, capturas de pantalla u otras imágenes en la do­cu­me­n­ta­ción. Para esto, basta con escribir una palabra de­s­cri­p­ti­va entre corchetes, seguida del URL de la imagen entre corchetes (sin espacios in­te­r­ca­la­dos). Delante de este, pon un signo de ex­cla­ma­ción para que Markdown lo in­te­r­pre­te como un archivo de imagen.

## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234

El formato Markdown permite crear viñetas de una lista no numerada con un asterisco (*) al principio de la línea.

Se pueden insertar enlaces en cualquier ubicación del archivo readme.md. El pro­ce­di­mie­n­to es muy similar al que se sigue con un archivo de imagen, solo que sin el signo de ex­cla­ma­ción al principio de la línea. Escribe la palabra que se enlazará entre corchetes, seguida de la ruta al sitio web también entre corchetes (y sin espacios in­te­r­ca­la­dos).

Nota

El archivo debe estar siempre en el mismo re­po­si­to­rio. También puedes utilizar otros archivos de acceso público, pero entonces corres el riesgo de que el pro­pie­ta­rio los borre en algún momento, con lo que tus archivos readme.md des­apa­re­ce­rían.

## Installation
***
A little intro about the installation. 
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start

Como los archivos readme suelen uti­li­zar­se en el contexto del de­sa­rro­llo de programas in­fo­r­má­ti­cos, es útil incluir en el documento ejemplos de código fuente. Markdown también tiene una opción de formato con este fin. Puedes formatear el código con tres acentos graves (```) al principio y al final. También puedes insertar los pasajes de código di­re­c­ta­me­n­te en el texto. 

## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.

Un “>” al principio de la línea convierte el texto en una cita. 

## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |

En el archivo readme.md también pueden uti­li­zar­se una co­m­bi­na­ción de listas ordenadas y no ordenadas. Para ello, solo tienes que continuar la lista numerada con el número co­rre­s­po­n­die­n­te.

Como ejemplo, hemos integrado palabras y secciones de texto en cursiva y en negrita. Puedes escribir en cursiva colocando un asterisco simple (*) o un guion bajo (_) antes o después de la palabra o sección de texto en cuestión. Los as­te­ri­s­cos dobles o los sub­ra­ya­dos se usan para marcar en negrita.

Ejemplos: plantilla de archivo readme

A co­n­ti­nua­ción, te mostramos de nuevo los ejemplos tratados en el artículo, esta vez resumidos en forma de plantilla de archivo readme:

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)
### General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](https://www.united-internet.de/fileadmin/user_upload/Brands/Downloads/Logo_IONOS_by.jpg)
## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234
## Installation
***
A little intro about the installation. 
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start
## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |
Consejo

El editor WYSIWYG de Dillinger te permitirá crear un archivo readme.md fá­ci­l­me­n­te.

Ir al menú principal