Plantilla README para Proyectos Open-Source e Internos

Overview

Un README es la puerta de entrada de tu proyecto. Es lo primero que ven los desarrolladores en GitHub, npm, PyPI o Docker Hub, y la mayoría decide en diez segundos si sigue leyendo o vuelve atrás. Un README bien estructurado responde tres preguntas rápido — qué es esto, cómo se instala, cómo se usa — y luego no estorba.

Esta plantilla te da un esqueleto probado que puedes copiar, adaptar y publicar en minutos. Está pensada para dos audiencias a la vez: personas que escanean la página del repo, y registros de paquetes que renderizan tu Markdown con sus propias peculiaridades (npm y PyPI no lo renderizan igual que GitHub — lo veremos más abajo).

Combínala con la Guía de Contribución y el Código de Conducta si el proyecto acepta contribuciones externas.

When to Use

Usa esta plantilla cuando:

• Empieces un proyecto open-source que necesita atraer usuarios y contribuidores
• Documentes una librería, CLI o servicio interno que otros equipos van a consumir
• Publiques un paquete en un registro público (npm, PyPI, Docker Hub, crates.io)
• Entregues un proyecto a otro equipo o a un nuevo maintainer

No necesitas la plantilla completa para scripts desechables o experimentos. Un README de tres líneas que diga qué hace el repo y cómo ejecutarlo siempre gana a uno largo y desactualizado — y si el proyecto ya tiene un sitio de documentación propio, mantén el README corto y enlaza a él en vez de duplicar contenido.

The Template

Copia la plantilla siguiente y reemplaza los marcadores [entre corchetes]. Elimina las secciones que no apliquen — un README con boilerplate vacío se lee peor que uno corto y honesto.

# [Nombre del Proyecto]

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/username/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/username/repo/actions)

> [Descripción de una línea de lo que hace este proyecto.]

## Tabla de Contenidos

- [Overview](#overview)
- [Instalación](#instalación)
- [Uso](#uso)
- [Configuración](#configuración)
- [Contribución](#contribución)
- [Licencia](#licencia)

## Descripción del Proyecto

[2-3 párrafos explicando qué hace el proyecto, por qué existe y quién debería usarlo.]

## Instalación

### Prerrequisitos

- [Node.js 20+](https://nodejs.org/)
- [Docker 24+](https://www.docker.com/) (opcional, para el setup con contenedores)

### Inicio Rápido

```bash
# Clonar el repositorio
git clone https://github.com/username/repo.git
cd repo

# Instalar dependencias
npm install

# Ejecutar el proyecto
npm run dev
```

## Uso

```javascript
import { createClient } from 'my-package';

const client = createClient({ timeout: 5000 });
const result = await client.fetch('/status');
console.log(result);
```

## Configuración

| Opción | Tipo | Default | Descripción |
|--------|------|---------|-------------|
| `timeout` | number | `5000` | Timeout de petición en milisegundos |
| `retries` | number | `3` | Número de reintentos |

## Referencia API

Ver [API.md](./docs/API.md) para la documentación completa de la API.

## Contribución

Aceptamos contribuciones. Lee [CONTRIBUTING.md](./CONTRIBUTING.md) antes de abrir un pull request.

## Licencia

[MIT](LICENSE) © [Nombre del Autor]

Explanation

Cada parte de la plantilla existe por una razón — entender el porqué facilita decidir qué recortar:

• Nombre + one-liner: el gancho. Si la primera frase no dice qué hace el proyecto, nada de lo que sigue se va a leer.
• Badges: estado del build, versión y licencia de un vistazo. Tres o cinco bastan; un muro de veinte badges transmite ruido, no salud.
• Tabla de Contenidos: merece la pena cuando el archivo supera las ~200 líneas. GitHub ya ofrece un botón de outline en la interfaz, así que el TOC manual importa sobre todo en npm, PyPI y renderizadores autoalojados.
• Descripción: dos o tres párrafos sobre qué hace, por qué existe y para quién es. Olvida el texto de marketing.
• Instalación: reduce la barrera hasta el primer éxito. Prerrequisitos primero, luego comandos que funcionan al pegarlos tal cual.
• Uso: un ejemplo mínimo que funciona. Los casos límite van en la documentación, no aquí.
• Referencia API: un enlace, no una copia. La documentación detallada vive en /docs o en el sitio de documentación para que el README siga siendo escaneable.
• Contribución: marca las expectativas para PRs, issues y estilo de código — enlaza a una Guía de Contribución dedicada en vez de escribir las reglas inline.
• Licencia: protege a autores y usuarios. Sin licencia, el proyecto es “todos los derechos reservados” por defecto, lo que bloquea legalmente casi cualquier uso.

Un buen one-liner sigue una forma simple: qué hace, para quién, y qué lo hace distinto. “Una máquina de estados simple para servicios TypeScript” le dice más al lector que “una solución moderna de gestión de estado”. Si no puedes escribir el one-liner sin buzzwords, el posicionamiento todavía no está claro — resuélvelo antes de rellenar el resto de la página.

El orden importa tanto como las secciones. Los lectores bajan de arriba a abajo y abandonan pronto, así que el diseño adelanta todo lo que un recién llegado necesita para llegar a “me funciona en mi máquina”:

Todo lo que está above the fold — en GitHub son más o menos las primeras 100 líneas — debería responder “qué es” y “cómo lo pruebo”. Si el lector tiene que pasar una disertación de arquitectura para encontrar el comando de instalación, el orden está mal.

How to Adapt This Template

No rellenes el documento de arriba abajo — trabaja en este orden:

1. One-liner y descripción primero. Si esas dos piezas no explican el proyecto, nada más lo salvará.
2. Instalación e inicio rápido después, y verifícalos en una máquina limpia o un contenedor antes de escribir otra línea. Una instalación que solo funciona en tu laptop es un bug, no un atajo.
3. Un ejemplo de uso que realmente corre — pégalo, ejecútalo, publícalo.
4. Todo lo demás al final: tablas de configuración, badges, enlaces de contribución. Los tres primeros bloques deciden si el lector se queda; una hora eligiendo badges antes de que el comando de instalación funcione es optimizar lo que no toca.

Adapt It to Your Registry

El mismo Markdown se renderiza distinto según dónde se publique. Estas son las diferencias que suelen morder:

GitHub renderiza la especificación completa de GitHub Flavored Markdown más un subconjunto saneado de HTML. Los enlaces relativos y las rutas relativas de imágenes funcionan porque GitHub los resuelve contra el repo. Los anchors a encabezados funcionan automáticamente y hay un botón de outline integrado para archivos largos.

npm muestra el README en la página del paquete pero lo renderiza fuera del contexto de tu repo. Los enlaces relativos (./docs/API.md) y las rutas relativas de imágenes se rompen — conviértelos en URLs absolutas, y fija las imágenes a una release etiquetada (https://raw.githubusercontent.com/user/repo/v1.2.0/docs/screenshot.png) para que las versiones antiguas del paquete sigan mostrando la captura correcta. Los enlaces a CONTRIBUTING.md o LICENSE también deberían ser absolutos.

PyPI renderiza el long_description en la página del proyecto usando un subconjunto de Markdown. El HTML complejo se elimina, algunos trucos de anchors fallan, y un README que se ve perfecto en GitHub puede fallar la validación twine check con “The description failed to render”. Configura long_description_content_type='text/markdown' en los metadatos del paquete y ejecuta twine check dist/* — o python -m readme_renderer sobre el archivo — antes de cada release. Los enlaces relativos se rompen aquí por la misma razón que en npm.

Docker Hub no lee el README de la imagen ni del repo automáticamente. Lo pegas a mano o lo subes con una herramienta como docker pushrm; mantén la versión de Docker Hub autocontenida porque los enlaces relativos al repo no resolverán.

La regla segura: escribe el README una vez con URLs absolutas para todo lo que tenga que funcionar fuera de GitHub, y reserva los enlaces relativos para la navegación interna del repo que usan los lectores de GitHub.

A Real README Example

Así queda la plantilla rellenada para un servicio interno — fíjate en cómo responde “ejecútalo”, “configúralo” y “opéralo” en ese orden:

# Payment Service

Servicio de procesamiento de pagos para la plataforma.

## Inicio Rápido

Requisitos:
  - Node.js 20+
  - Docker 24+
  - PostgreSQL 16+

Instalación:
  git clone https://github.com/company/payment-service.git
  cd payment-service
  npm install
  cp .env.example .env  # edita con tus valores
  docker compose up -d  # postgres y redis
  npm run db:migrate
  npm run dev

Tests:
  npm test           # tests unitarios
  npm run test:e2e   # tests end-to-end
  npm run test:cov   # reporte de cobertura

## Endpoints

  POST   /payments               Crear un pago
  GET    /payments/:id           Obtener un pago
  POST   /payments/:id/refund    Reembolsar un pago
  GET    /health                 Health check

## Configuración

  Variable          | Requerida | Default | Descripción
  ------------------|-----------|---------|-------------------
  DATABASE_URL      | Sí        | -       | URL de PostgreSQL
  REDIS_URL         | Sí        | -       | URL de Redis
  CARRIER_API_KEY   | Sí        | -       | API key del carrier
  LOG_LEVEL         | No        | info    | Nivel de logging
  PORT              | No        | 3000    | Puerto del servidor

## Monitoreo

  - Dashboard: https://grafana.company.com/d/payment
  - Alertas: servicio PagerDuty PD-1234
  - SLO: 99.9% de disponibilidad, p95 < 500ms

## Contribuir

  Ver CONTRIBUTING.md para el flujo de contribución.
  Contacto: #payments-team en Slack.

Dos cosas que vale la pena copiar de este ejemplo más allá de la estructura: la tabla de variables de entorno hace el servicio operable sin leer el código fuente, y el bloque de monitoreo le dice al ingeniero de guardia dónde mirar a las 3 a.m. Para servicios internos, esas dos secciones convierten el README de un trámite en un documento operativo — se solapan con lo que cubre en profundidad la Plantilla de Runbook.

A Minimal README for Small Projects

No todo repo necesita la plantilla completa. Una librería de una sola función, una herramienta personal o un script pequeño se lee mejor con un README que cabe en una pantalla:

# clip-fetch

Trae JSON con timeout y reintento incorporados. Cero dependencias.

## Instalar

```bash
npm install clip-fetch
```

## Uso

```js
import { fetchJson } from 'clip-fetch';

const data = await fetchJson('/api/status', { timeout: 3000 });
```

API: `fetchJson(url, options?)` → `Promise<any>`

[MIT](LICENSE)

Once líneas cubren qué hace, cómo se instala y cómo se llama — que es todo lo que necesita la audiencia de una utilidad pequeña. La regla práctica: toda sección de la plantilla completa es opcional excepto qué hace, cómo se instala, cómo se usa y la licencia. Haz crecer el README solo cuando los lectores empiecen a hacer preguntas que no responde.

Variants

La plantilla es un punto de partida, no un uniforme. Qué añadir y qué omitir depende del tipo de proyecto:

Tipo de Proyecto	Secciones a Agregar	Secciones a Omitir
Librería / SDK	Referencia API, Changelog	Screenshots, Monitoreo
Herramienta CLI	Comandos, Flags, Autocompletado	Arquitectura
App Web	Screenshots, Demo, Botón de deploy	Referencia API
Herramienta Interna	Onboarding, Enlace a runbook, Canal de Slack	Licencia, Contribución
Monorepo	Mapa de paquetes, enlaces a README por paquete	Sección única de instalación

• Las librerías y SDKs viven o mueren por su documentación de API. Enlaza pronto a la referencia completa y mantén al menos un ejemplo de código por feature principal en el propio README.
• Las herramientas CLI deberían mostrar la salida real del terminal, no solo el comando — una transcripción de cinco líneas de cómo se ve el éxito elimina la mayoría de los issues de “¿funcionó?”.
• Las apps web se benefician más de un screenshot above the fold que de cualquier párrafo que puedas escribir.
• Las herramientas internas pueden prescindir de licencia y marketing, pero necesitan un responsable, un canal de Slack y un enlace a la checklist de onboarding o al runbook. Nadie externo la va a leer, así que escribe para el compañero que la depura a medianoche.
• Los monorepos necesitan un mapa, no un ensayo: una tabla que enlace cada paquete a su propio README, más instrucciones a nivel raíz para la toolchain compartida — instala una vez, compila todo. Cada README de paquete debería sostenerse solo, porque los consumidores de @org/package-x aterrizan en su página de npm, no en la raíz de tu monorepo.

What Works

• Mantén las primeras 100 líneas escaneables — la mayoría de lectores no pasa del fold, así que adelanta nombre, gancho e instalación.
• Usa un GIF de demo o screenshot — la prueba visual gana a los párrafos, pero mantenlo por debajo de ~2 MB o las páginas de paquetes cargan lento.
• Enlaza, no incluyas — la documentación detallada pertenece a /docs o al sitio de documentación; el README debe apuntar a ella, no duplicarla.
• Automatiza el TOC — las tablas de contenido desactualizadas frustran; ejecuta doctoc o markdown-toc como pre-commit hook o job de CI.
• Testea los ejemplos — los snippets que no compilan erosionan la confianza más rápido que la falta de documentación; ejecútalos en CI con un job tipo doctest o un script que extraiga y corra los bloques de código.
• Enlaza el changelog — los usuarios necesitan saber qué cambió entre versiones; la Plantilla de Changelog te da una estructura compatible con Keep a Changelog.
• Limita los badges — elige las tres a cinco señales que un recién llegado realmente revisa (CI, versión, licencia, cobertura) y elimina el resto.

Common Mistakes

• Sin instrucciones de instalación — el fallo más común con diferencia; asume que el lector tiene cero contexto.
• Prerrequisitos faltantes — síndrome de “en mi máquina funciona”; lista versiones de runtime, restricciones de SO y cuentas o API keys requeridas.
• Muro de texto — divide la prosa larga en secciones, listas y tablas; nadie lee introducciones de seis párrafos.
• Ejemplos desactualizados — un ejemplo de código que falla al pegarlo es peor que no tenerlo; conecta el README a CI para que los ejemplos sigan siendo honestos.
• Sin licencia — sin una, el proyecto es “todos los derechos reservados” y la mayoría de empresas no puede tocarlo, mucho menos contribuir.
• Copiar de otro proyecto — nombres de repo obsoletos, badges incorrectos y enlaces muertos delatan que nadie lo revisó.
• Enlaces relativos que se rompen fuera de GitHub — ./docs/api.md y ./images/screenshot.png dan 404 en npm y PyPI; usa URLs absolutas para todo lo que renderice un registro.
• Spam de badges — veinte shields diciendo “build: passing” no le dicen nada al lector; cada badge debería ganarse su fila de píxeles.

Troubleshooting

• Los badges se rompieron tras renombrar o transferir el repo: las URLs de shields.io y de los badges de CI siguen apuntando al antiguo dueño o nombre. Actualiza todas las URLs de badges y comprueba que el redirect de GitHub no esté enmascarando el problema — los badges resuelven a través del redirect hasta que expire.
• El README se ve en GitHub pero falla en PyPI: PyPI solo soporta un subconjunto de Markdown y elimina casi todo el HTML. Ejecuta twine check dist/* antes de subir; los culpables habituales son las etiquetas <details>, tablas complejas dentro de listas y sintaxis de imágenes que el renderer de PyPI rechaza.
• Enlaces o imágenes 404 en la página del paquete en npm: npm renderiza el README sin contexto del repo, así que toda ruta relativa se rompe. Convierte enlaces y src de imágenes a URLs absolutas, fijando las imágenes a un tag de release en vez de a main para que la documentación sea consistente por versión.
• La Tabla de Contenidos se desincroniza: genérala en vez de escribirla a mano — doctoc README.md o markdown-toc -i README.md en un pre-commit hook mantiene los anchors honestos a medida que las secciones se mueven.
• El README se ve bien en local pero truncado en el registro: Docker Hub y algunos registros limitan la longitud renderizada o el tamaño del campo. Mantén el README del registro ligero y enlaza al sitio de documentación para el resto.
• Los anchors no saltan en GitHub: GitHub genera los anchors desde el texto renderizado del encabezado — minúsculas, espacios como guiones, sin puntuación. Los caracteres no ASCII y los encabezados duplicados producen anchors distintos de lo que esperarías; revisa el href real en el código fuente de la página antes de enlazar.
• Un badge muestra un estado viejo o incorrecto: GitHub sirve las imágenes de badges a través de su proxy de imágenes camo, que las cachea — un badge puede ir por detrás de la realidad un tiempo después de que el estado subyacente cambie. Dale tiempo antes de asumir que algo está roto, y revisa la URL del badge en sí en vez de la página renderizada.

Keep It Alive

Los READMEs se pudren en silencio: los enlaces mueren cuando los repos se mueven, los ejemplos se desincronizan del código, los badges sobreviven al job de CI al que apuntaban. Un README equivocado es peor que uno al que le faltan secciones, porque los lectores confían en él hasta que los quema una vez.

• Asigna un responsable. Una entrada de CODEOWNERS para README.md hace que los cambios de documentación los revise alguien que conoce el proyecto, no quien resulte estar libre.
• Ponlo en el checklist del PR. “¿Este cambio afecta al README?” tarda cinco segundos en responderse y atrapa la mayor parte del desfase antes de que aterrice.
• Verifica enlaces en CI. lychee o markdown-link-check corriendo por la noche marca enlaces muertos y anchors movidos sin que nadie tenga que acordarse.
• Revísalo con cadencia. Una vez por release o por trimestre — lo que llegue primero. Cuando el proyecto cambia de forma (herramienta interna que pasa a open source, monorepo dividido, nuevo dueño), revisa toda la estructura, no solo las palabras.

Pre-Publish Checklist

Antes de hacer público el repo o cortar una release, recorre esta lista una vez — toma diez minutos y atrapa la mayoría de los errores de README:

• Pasos de instalación e inicio rápido probados en una máquina limpia o un contenedor nuevo, sin herramientas globales asumidas
• Todos los enlaces y badges resuelven a este repo, no a los marcadores username/repo de la plantilla
• El archivo LICENSE existe, con el año y el titular del copyright rellenados
• El archivo se renderiza bien en cada registro donde publiques — twine check dist/* para PyPI, una vista previa del tarball empaquetado para npm
• Los screenshots y GIFs muestran la UI actual, no la de hace dos releases
• Tabla de Contenidos regenerada tras el último cambio de encabezados
• La vía de contacto es real — un canal de Slack, issue tracker o email que alguien realmente monitorea
• No quedan marcadores [entre corchetes] — busca \[ antes de etiquetar la release

Further Reading

• Especificación GitHub Flavored Markdown — la sintaxis exacta que renderiza GitHub, incluidas las partes que los registros no soportan
• Making a PyPI-friendly README — guía oficial de PyPA sobre long_description y sus peculiaridades de renderizado
• shields.io — generador de badges para licencia, versión, estado de CI y cobertura
• Recursos complementarios — archivo de plantilla descargable y el ejemplo completo de payment-service