Archivo readme: resumen con plantilla

Readme: el propio nombre, léeme, indica su propósito: ser leído. El archivo readme es el primer archivo que un desarrollador debe mirar antes de embarcarse en un proyecto, por lo que también es esencial saber cómo escribir un buen archivo readme, para que toda la informació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 información importante sobre el sistema, proyecto o software al que se refieren. Para que los usuarios puedan encontrar fácilmente el archivo de un vistazo, se recomienda ubicarlo en el nivel superior del directorio.

Consejo

En general, en el nombre del archivo se escribe README en mayúsculas. De este modo, los sistemas que diferencian entre mayúsculas y minúsculas listarán el archivo antes que todos los demás archivos que empiezan con minúsculas.

El archivo tiene también distintos propósitos para los distintos tipos de usuarios:

  • Para el usuario final, los archivos readme aclaran posibles preguntas sobre la instalación, actualización o utilización de un software.
  • Un archivo readme ofrece varias ventajas para tu propia labor de desarrollo. Por un lado, antes de empezar con el desarrollo propiamente 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 desarrolladores, los archivos readme explican el código y proporcionan información importante sobre su desarrollo posterior o sobre cómo utilizar un sistema, un software o proyectos de código abierto.

¿Qué debería contener un archivo readme?

Dependiendo de su propósito, un archivo readme puede ofrecer los siguientes contenidos:

  • Una descripción general del sistema o proyecto.
  • El estado del proyecto, que es particularmente importante si el proyecto está todavía en desarrollo. En él se mencionan los cambios planeados y la dirección de desarrollo del proyecto, y se especifica directamente si un proyecto está terminado.
  • Los requisitos del entorno de desarrollo para la integración.
  • Una guía para la instalación y el funcionamiento.
  • Una lista de las tecnologías utilizadas y, cuando proceda, enlaces con más información.
  • Los proyectos de código abierto que se pueden modificar o desarrollar deben incluir una sección de colaboración deseada en el archivo readme.md: ¿cómo se solucionan los problemas? ¿Cómo deberían los desarrolladores impulsar los cambios?
  • Bugs conocidos y posibles correcciones de errores.
  • Sección de preguntas frecuentes con todas las preguntas planteadas hasta la fecha.
  • Información sobre derechos de autor y licencias.

Es importante 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. Dependiendo de la plataforma 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 visualización de texto. Así se garantiza que el programa de texto pueda leer el archivo.

Hoy en día, los desarrolladores usan generalmente 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 caracteres de formateo. Un archivo readme correctamente formado y estructurado ofrece a los usuarios un resumen completo del proyecto.

Readme.md: ejemplo en formato Markdown

Aquí te mostramos cada uno de los elementos estructurales de un archivo readme.md así como las posibilidades que ofrece el formato Markdown. Para permitir la colaboración en todo el mundo y evitar barreras lingüísticas, 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 asteriscos (***) puedes insertar una línea de separación horizontal.

Arriba del todo, en el archivo readme, se incluye un nombre de proyecto significativo y una breve explicación sobre el tipo de proyecto. En Markdown, la almohadilla (#) siempre introduce un encabezado. El número de almohadillas determina el tipo de encabezado:

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

Si la documentación es extensa, un índice claro proporciona 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 estructurarse fácilmente con una lista ordenada. Basta con insertar el número que corresponda al principio de la línea para crear la lista.

GitHub añade automáticamente identificaciones a los encabezados del archivo readme. Las identificaciones se generan a partir del nombre del encabezado, y los guiones (-) reemplazan los espacios. Son excelentes para la navegación de anclaje del índice de contenido. Si el archivo readme.md pretende usarse en otra plataforma que no asigne automáticamente identificaciones a los encabezados, la navegació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 respectivos de las secciones individuales:

## 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 información general del proyecto es importante para hacerse una idea de este más allá de la breve explicación. Markdown permite también insertar gráficos, capturas de pantalla u otras imágenes en la documentación. Para esto, basta con escribir una palabra descriptiva entre corchetes, seguida del URL de la imagen entre corchetes (sin espacios intercalados). Delante de este, pon un signo de exclamación para que Markdown lo interprete 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 procedimiento es muy similar al que se sigue con un archivo de imagen, solo que sin el signo de exclamació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 intercalados).

Nota

El archivo debe estar siempre en el mismo repositorio. También puedes utilizar otros archivos de acceso público, pero entonces corres el riesgo de que el propietario los borre en algún momento, con lo que tus archivos readme.md desaparecerí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 utilizarse en el contexto del desarrollo de programas informáticos, 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 directamente 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 utilizarse una combinación de listas ordenadas y no ordenadas. Para ello, solo tienes que continuar la lista numerada con el número correspondiente.

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 asteriscos dobles o los subrayados se usan para marcar en negrita.

Ejemplos: plantilla de archivo readme

A continuació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ácilmente.

¿Le ha resultado útil este artículo?