# README y guía de incorporación

Produce el documento que lee primero quien llega nuevo — y con el que puede trabajar sin preguntar nada que el documento debería haber respondido.

## Entregable

Un documento Markdown, `readme.md`, con la estructura fijada en **Salida** más abajo. Es la puerta desde la que se alcanza el resto de la documentación del proyecto, y una entrada de **Auditoría de documentación**.

## Entradas obligatorias

- **Acceso al repositorio** — el árbol entero, incluidos los archivos de compilación, dependencias y configuración.
- **Una máquina donde ejecutar la instalación** — cada paso de este documento se ejecuta antes de escribirse.
- **Para quién es** — alguien que acaba de entrar al equipo, alguien de fuera que contribuye, o alguien que vuelve tras mucho tiempo; necesitan cosas distintas.

Sin acceso al repositorio, detente e infórmalo. Sin una máquina donde ejecutar la instalación la guía todavía se puede escribir, pero cada paso queda marcado `sin verificar` y el documento lo declara arriba.

## Entradas opcionales

- Quiénes mantienen el proyecto y dónde responden preguntas
- El proceso de revisión y contribución, y las reglas de ramas que lo acompañan
- Un documento de incorporación existente y las preguntas que no supo responder
- Los sistemas operativos soportados y las diferencias entre ellos
- Las cuentas, credenciales o accesos que hay que solicitar antes de empezar
- Los fallos de instalación conocidos y en qué acaban siendo

Una entrada opcional ausente se convierte en un hueco con nombre en la sección 9, no en una frase plausible. Una guía que adivina qué accesos hacen falta manda a quien llega a la persona equivocada.

## Ejecución

**1 — Declarar qué es esto y qué no.** Dos o tres frases: qué hace el proyecto, quién lo usa y qué cosas cercanas no es. Quien haya entendido mal el propósito leerá mal todas las instrucciones que vengan después.

**2 — Tomar los requisitos del proyecto, no de la costumbre.** Lee los archivos de dependencias, compilación y configuración y saca de ahí las versiones exigidas. Donde haya una versión fijada, escribe la fijación. Donde se admita un rango, escribe el rango. Una versión tomada de lo que casualmente hay instalado en una máquina es una conjetura con un número encima.

**3 — Ejecutar la instalación sobre una copia limpia y anotar lo que hiciste.** Cada comando en el orden en que se ejecutó, incluidos los que hicieron falta y no estaban documentados en ninguna parte. Si un paso necesitó un acceso que tú ya tenías, dilo — es un requisito que quien llega todavía no tiene.

**4 — Arrancarlo y después probarlo.** Registra el comando que arranca el proyecto, qué debe ver el lector cuando funcionó, el comando que ejecuta las pruebas y qué aspecto tiene una ejecución correcta. Quien no pueda distinguir el éxito del silencio seguirá adelante y romperá algo más lejos.

**5 — Mapear el árbol.** Los directorios que quien llega va a tocar, qué vive en cada uno y dónde va algo nuevo de cada tipo. Salta las partes que nadie edita a mano; aquí solo son ruido.

**6 — Escribir las convenciones por las que se le corregiría.** Forma del mensaje de commit, nombres de rama, formato, la revisión por la que debe pasar un cambio y lo que el proyecto rechaza automáticamente. Una convención no escrita es una regla que quien llega descubre en la revisión.

**7 — Nombrar dónde preguntar.** El sitio al que van las preguntas, quién las responde y qué incluir en la pregunta. Después marca `sin verificar` cada paso que no pudiste ejecutar.

## Salida

`readme.md`, en este orden:

- **1. Qué es esto** — propósito, quién lo usa y qué no es
- **2. Requisitos previos** — por requisito: cuál, la versión que el proyecto exige y el archivo del que se leyó esa versión
- **3. Accesos y cuentas** — qué hay que solicitar antes de empezar y a quién
- **4. Instalación** — comandos numerados, cada uno con su resultado esperado y si se ejecutó
- **5. Cómo arrancarlo** — el comando, la salida esperada y el primer fallo habitual
- **6. Cómo probarlo** — el comando, qué aspecto tiene una ejecución correcta y qué hacer con una fallida
- **7. Estructura del proyecto** — directorio, qué vive ahí y dónde va el trabajo nuevo de ese tipo
- **8. Convenciones** — las reglas contra las que se revisa un cambio
- **9. Dónde preguntar y qué falta** — quién responde y cada paso marcado `sin verificar`

## Validación

El documento está listo cuando se cumple todo esto:

- Cada comando de las secciones 4 a 6 se ejecutó, o está marcado `sin verificar`
- Cada versión de la sección 2 cita el archivo del proyecto del que se leyó
- La sección 4 parte de una copia limpia y no supone ningún estado previo
- Las secciones 5 y 6 declaran cada una qué aspecto tiene el éxito
- La sección 1 dice qué no es el proyecto, al menos en una frase
- No se nombra ninguna herramienta, servicio ni cuenta sin decirle a quien llega cómo conseguirla

Falla la ejecución si aparece una versión que no se leyó de un archivo del proyecto, o si un comando documentado nunca se ejecutó y no está marcado `sin verificar`.

## Gestión de fallos

- **Sin acceso al repositorio** — detente. Informa de que una incorporación no se puede escribir a partir de la descripción de un proyecto.
- **La instalación no se puede completar** — documenta hasta el paso que falló, registra el fallo con su mensaje exacto, marca los pasos restantes como `sin verificar` y lista el bloqueo en la sección 9. No escribas los pasos que esperarías que vinieran después.
- **Pasos manuales no documentados** — regístralos como pasos con su propio número, no como una nota al margen. El paso que alguien hace de memoria es el que quien llega no encuentra nunca.
- **Los requisitos se contradicen entre archivos** — registra cada versión con el archivo del que viene, marca el punto como `en disputa` y elévalo a la sección 9 como bloqueante.
- **Sin contacto con nombre** — escribe `desconocido` en la sección 9 y declara que quien llega no tiene dónde preguntar. Una guía que termina sin una ruta hacia una persona deja de funcionar la primera vez que se equivoca.