{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Escribir un README que sirva\n",
    "\n",
    "La portada de tu proyecto y la razón por la que alguien lo usa o se va\n",
    "\n",
    "Cuaderno de soluciones del capítulo 18 de **Git desde cero**, de Miss Yera.\n",
    "\n",
    "Corre de arriba abajo. Si lo abres en Google Colab no necesitas instalar nada.\n",
    "\n",
    "Capítulo completo: https://missyera.com/guias/git-desde-cero/escribir-un-readme/\n",
    "\n",
    "Este es el cuaderno de **soluciones**. Trae el código de cada ejercicio, la\n",
    "explicación de la trampa y la respuesta del quiz. Si vienes del cuaderno de\n",
    "práctica sin haberlo intentado, vuelve 🙂"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Antes de empezar\n",
    "\n",
    "Este capítulo son comandos de terminal, no Python. La celda de abajo baja el\n",
    "ayudante que los ejecuta y que **recuerda en qué carpeta quedaste**, que es lo\n",
    "que hace falta para que un `cd` de una celda siga valiendo en la siguiente.\n",
    "\n",
    "A partir de ahí, cada celda de comandos empieza por `%%consola`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import urllib.request\n",
    "\n",
    "# El ayudante de los cuadernos. Trae la corrección de los ejercicios y, en los\n",
    "# capítulos de consola, la celda mágica que ejecuta los comandos. Se baja en\n",
    "# vez de venir pegado aquí para que siempre sea el último.\n",
    "urllib.request.urlretrieve(\n",
    "    \"https://missyera.com/static/cuadernos/revisa.py\", \"revisa.py\")\n",
    "import revisa\n",
    "revisa.carga({}, lenguaje=\"bash\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "El README es lo primero que se ve al entrar a un repositorio, y en la\n",
    "mayoría de proyectos es también lo único que se lee. Es tu portada 🎯\n",
    "\n",
    "Y hay una prueba muy simple para saber si el tuyo sirve: dáselo a alguien\n",
    "que no conoce el proyecto y mira si llega solo hasta la primera salida en\n",
    "pantalla. Si tiene que preguntarte algo, falta eso en el README."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Markdown en cinco símbolos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "El `.md` del final significa markdown, que es texto normal con\n",
    "unas marcas. Estas cinco resuelven el 95%:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "| Escribes | Se ve |\n",
    "|---|---|\n",
    "| `# Título` | Un título grande |\n",
    "| `## Sección` | Un título mediano |\n",
    "| `**negrita**` | En negrita |\n",
    "| `- item` | Una lista con viñetas |\n",
    "| Tres tildes invertidas | Un bloque de código |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Las cuatro secciones que no pueden faltar"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Vamos a escribir el README del proyecto de ventas, entero, y a mirarlo:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "mkdir ventas-miss-yera\n",
    "cd ventas-miss-yera\n",
    "git init -q\n",
    "printf 'ciudad,monto\\nLima,1200\\nArequipa,890\\n' > ventas.csv\n",
    "printf 'pandas\\n' > requirements.txt\n",
    "cat > README.md <<'FIN'\n",
    "# Ventas Miss Yera\n",
    "\n",
    "Calcula el total de ventas por ciudad a partir de un CSV.\n",
    "\n",
    "## Necesitas\n",
    "\n",
    "- Python 3.11 o superior\n",
    "\n",
    "## Instalar\n",
    "\n",
    "```\n",
    "python3 -m venv .venv\n",
    "source .venv/bin/activate\n",
    "pip install -r requirements.txt\n",
    "```\n",
    "\n",
    "## Usar\n",
    "\n",
    "```\n",
    "python3 total.py ventas.csv\n",
    "```\n",
    "\n",
    "Devuelve el monto total por ciudad, ordenado de mayor a menor.\n",
    "FIN\n",
    "git add .\n",
    "git commit -q -m \"Se escribe el README del proyecto de ventas\"\n",
    "cat README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fíjate en el orden: **qué hace, qué necesitas, cómo se instala, cómo\n",
    "se usa**. Nadie llegó al proyecto para leer sobre arquitectura modular\n",
    "escalable; llegó para hacerlo andar 🏃‍♀️"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lo que va después, si quieres"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Un ejemplo de la salida, que vale por tres párrafos.\n",
    "\n",
    "- La licencia, que vimos en 16.\n",
    "\n",
    "- Cómo contribuir, si esperas que alguien lo haga.\n",
    "\n",
    "- A quién escribir si algo falla.\n",
    "\n",
    "Y una cosa que no va: la lista de \"tecnologías utilizadas\" con veinte\n",
    "logos. A quien va a usarlo le da igual, y a quien va a contratarte también 🙃"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ampliarlo sin romperlo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cat >> README.md <<'FIN'\n",
    "\n",
    "## Ejemplo de salida\n",
    "\n",
    "```\n",
    "Lima        1200\n",
    "Arequipa     890\n",
    "```\n",
    "\n",
    "## Licencia\n",
    "\n",
    "MIT\n",
    "FIN\n",
    "git add README.md\n",
    "git commit -q -m \"Se agregan el ejemplo de salida y la licencia al README\"\n",
    "tail -12 README.md\n",
    "git log --oneline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El README de tu perfil"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hay un truco que casi nadie conoce y que a mí me parece de los más útiles\n",
    "para quien está armando su portafolio: si creas un repositorio\n",
    "**con el mismo nombre que tu usuario** y le pones un\n",
    "`README.md`, GitHub lo muestra en tu perfil."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cd ..\n",
    "mkdir mi-usuario\n",
    "cd mi-usuario\n",
    "git init -q\n",
    "cat > README.md <<'FIN'\n",
    "## Hola, soy Gera\n",
    "\n",
    "Trabajo con datos e IA en empresas de consumo masivo.\n",
    "\n",
    "- Analizo ventas por ciudad y canal\n",
    "- Automatizo reportes que antes se hacían a mano\n",
    "- Escribo en missyera.com\n",
    "FIN\n",
    "git add README.md\n",
    "git commit -q -m \"README del perfil\"\n",
    "cat README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Eso es lo que ve quien entra a tu perfil antes de mirar ningún proyecto. Si\n",
    "estás buscando trabajo con datos, ese archivo trabaja para ti todos los\n",
    "días 💼"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La trampa\n",
    "\n",
    "Publicas tu analizador de ventas con un README bonito que explica qué hace, para qué sirve y quién lo escribió. Nadie lo usa.\n",
    "\n",
    "```\n",
    "# Analizador de ventas\n",
    "\n",
    "Herramienta de analisis de ventas multicanal desarrollada\n",
    "con un enfoque modular y escalable para el sector retail.\n",
    "\n",
    "## Autor\n",
    "Yo\n",
    "\n",
    "## Licencia\n",
    "MIT\n",
    "```\n",
    "\n",
    "**Qué está mal**\n",
    "\n",
    "No hay una sola línea que diga cómo se pone en marcha 🤔\n",
    "\n",
    "Quien llega a tu README ya sabe más o menos qué hace, porque para eso entró. Lo que no sabe es qué escribir en la terminal para verlo funcionando, y si en treinta segundos no lo encuentra, se va al siguiente proyecto.\n",
    "\n",
    "Las tres cosas que no pueden faltar son **qué necesito instalado, cómo lo instalo y cómo lo ejecuto**, con los comandos copiables. Todo lo demás es decoración.\n",
    "\n",
    "La prueba que uso: dárselo a alguien que no conoce el proyecto y ver si llega solo hasta la primera salida en pantalla."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comprueba que se entendió"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comprueba que lo tienes\n",
    "\n",
    "Tienes cinco minutos para mejorar un README. ¿Qué agregas primero?\n",
    "\n",
    "a) Los comandos exactos para instalarlo y ejecutarlo\n",
    "\n",
    "b) Una descripción más completa de qué hace el proyecto\n",
    "\n",
    "c) Una lista de las tecnologías que usaste\n",
    "\n",
    "d) Un logo y unas insignias de colores\n",
    "\n",
    "---\n",
    "\n",
    "**La correcta es la a.**\n",
    "\n",
    "*b)* Quien llegó ya sabe más o menos qué hace. Lo que no sabe es cómo ponerlo en marcha.\n",
    "\n",
    "*c)* Es lo que menos se lee. Ocupa espacio arriba y no resuelve nada.\n",
    "\n",
    "*d)* Decoran, y no ayudan a nadie a llegar a la primera salida en pantalla.\n",
    "\n",
    "Un README bueno se mide en si el otro llegó solo hasta el final 🎯"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ejercicios"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Escribe el esqueleto\n",
    "\n",
    "Crea el proyecto del reporte por canal con un README de\n",
    "cuatro secciones."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cd ..\n",
    "mkdir reporte-canales\n",
    "cd reporte-canales\n",
    "git init -q\n",
    "printf 'canal,monto\\nBodegas,4200\\n' > canales.csv\n",
    "cat > README.md <<'FIN'\n",
    "# Reporte por canal\n",
    "\n",
    "Resume las ventas por canal a partir de un CSV.\n",
    "\n",
    "## Necesitas\n",
    "- Python 3.11\n",
    "\n",
    "## Instalar\n",
    "```\n",
    "pip install pandas\n",
    "```\n",
    "\n",
    "## Usar\n",
    "```\n",
    "python3 reporte.py canales.csv\n",
    "```\n",
    "FIN\n",
    "git add .\n",
    "git commit -q -m \"README del reporte por canal\"\n",
    "cat README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "# Reporte por canal\n",
    "\n",
    "Resume las ventas por canal a partir de un CSV.\n",
    "\n",
    "## Necesitas\n",
    "- Python 3.11\n",
    "\n",
    "## Instalar\n",
    "```\n",
    "pip install pandas\n",
    "```\n",
    "\n",
    "## Usar\n",
    "```\n",
    "python3 reporte.py canales.csv\n",
    "```\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cuatro secciones y cabe en una pantalla. Así se lee."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Agrega el ejemplo de salida\n",
    "\n",
    "Un ejemplo real explica más que un párrafo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cat >> README.md <<'FIN'\n",
    "\n",
    "## Ejemplo\n",
    "```\n",
    "Bodegas   4200\n",
    "```\n",
    "FIN\n",
    "git add README.md\n",
    "git commit -q -m \"Se agrega el ejemplo de salida\"\n",
    "tail -6 README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "```\n",
    "\n",
    "## Ejemplo\n",
    "```\n",
    "Bodegas   4200\n",
    "```\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Quien lo lea ya sabe qué esperar antes de instalar nada."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Cuenta cuántas líneas tiene\n",
    "\n",
    "Un README de doscientas líneas no lo lee nadie."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "wc -l README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "21 README.md\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Entre veinte y cincuenta líneas es un buen sitio donde estar."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Comprueba que están las secciones clave\n",
    "\n",
    "Lista los títulos del archivo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "grep \"^#\" README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "# Reporte por canal\n",
    "## Necesitas\n",
    "## Instalar\n",
    "## Usar\n",
    "## Ejemplo\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Este grep es mi revisión rápida: si no veo \"Instalar\" y \"Usar\", falta lo\n",
    "importante."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Enlaza otro archivo del proyecto\n",
    "\n",
    "En markdown, un enlace es texto entre corchetes y destino\n",
    "entre paréntesis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "printf 'MIT License\\n' > LICENSE\n",
    "cat >> README.md <<'FIN'\n",
    "\n",
    "Ver la [licencia](LICENSE).\n",
    "FIN\n",
    "git add .\n",
    "git commit -q -m \"Se enlaza la licencia desde el README\"\n",
    "tail -2 README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "Ver la [licencia](LICENSE).\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "GitHub convierte ese enlace en un clic que lleva al archivo."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6. Arma el README de tu perfil\n",
    "\n",
    "El repositorio que se llama igual que tu usuario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cd ..\n",
    "mkdir perfil\n",
    "cd perfil\n",
    "git init -q\n",
    "cat > README.md <<'FIN'\n",
    "## Hola\n",
    "\n",
    "- Analizo ventas por ciudad y canal\n",
    "- Automatizo reportes\n",
    "FIN\n",
    "git add README.md\n",
    "git commit -q -m \"README del perfil\"\n",
    "cat README.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "## Hola\n",
    "\n",
    "- Analizo ventas por ciudad y canal\n",
    "- Automatizo reportes\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Es el único repositorio de GitHub que se muestra fuera de su propia\n",
    "página 🪪"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7. Pide un archivo que no escribiste\n",
    "\n",
    "Intenta mostrar un README que no existe en esta carpeta."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%consola\n",
    "cat CONTRIBUTING.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "cat: CONTRIBUTING.md: No such file or directory\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\"No such file or directory\" es el error más común de la terminal, y casi\n",
    "siempre significa que estás en otra carpeta 📁"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lo que te llevas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Qué hace, qué necesitas, cómo se instala y cómo se usa. Si alguien\n",
    "llega solo hasta la primera salida, tu README sirve.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "Ese era el capítulo 18 de **Git desde cero**. El texto completo, con las salidas de cada bloque, está en https://missyera.com/guias/git-desde-cero/escribir-un-readme/\n",
    "\n",
    "Que tengas lindo día! 🌸"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}