{
 "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 práctica 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",
    "Los ejercicios están al final y traen una celda vacía debajo de cada uno. Las\n",
    "respuestas viven en el cuaderno de soluciones, y merece la pena pelearse un\n",
    "rato antes de abrirlo 💛"
   ]
  },
  {
   "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({\n",
    "    1: \"IyBSZXBvcnRlIHBvciBjYW5hbAoKUmVzdW1lIGxhcyB2ZW50YXMgcG9yIGNhbmFsIGEgcGFydGlyIGRlIHVuIENTVi4KCiMjIE5lY2VzaXRhcwotIFB5dGhvbiAzLjExCgojIyBJbnN0YWxhcgpgYGAKcGlwIGluc3RhbGwgcGFuZGFzCmBgYAoKIyMgVXNhcgpgYGAKcHl0aG9uMyByZXBvcnRlLnB5IGNhbmFsZXMuY3N2CmBgYA==\",\n",
    "    2: \"YGBgCgojIyBFamVtcGxvCmBgYApCb2RlZ2FzICAgNDIwMApgYGA=\",\n",
    "    3: \"MjEgUkVBRE1FLm1k\",\n",
    "    4: \"IyBSZXBvcnRlIHBvciBjYW5hbAojIyBOZWNlc2l0YXMKIyMgSW5zdGFsYXIKIyMgVXNhcgojIyBFamVtcGxv\",\n",
    "    5: \"VmVyIGxhIFtsaWNlbmNpYV0oTElDRU5TRSku\",\n",
    "    6: \"IyMgSG9sYQoKLSBBbmFsaXpvIHZlbnRhcyBwb3IgY2l1ZGFkIHkgY2FuYWwKLSBBdXRvbWF0aXpvIHJlcG9ydGVz\",\n",
    "    7: \"Y2F0OiBDT05UUklCVVRJTkcubWQ6IE5vIHN1Y2ggZmlsZSBvciBkaXJlY3Rvcnk=\",\n",
    "}, 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?** La respuesta está en el cuaderno de soluciones. Míralo tú primero."
   ]
  },
  {
   "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"
   ]
  },
  {
   "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": [
    "%%revisa 1\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 2\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 3\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 4\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 5\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 6\n",
    "# tu turno"
   ]
  },
  {
   "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": [
    "%%revisa 7\n",
    "# tu turno"
   ]
  },
  {
   "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
}