Escribir capítulos para la web de un curso que expliquen el porqué antes de la fórmula

## Saber dónde van las páginas del curso y sus traducciones El proyecto es un sitio de documentación estático construido a partir de archivos fuente del repositorio. Mantén el árbol predecible para que quien contribuya pueda adivinar dónde se encuentra cada cosa: - `docs/` — el contenido del curso que se convierte en las páginas publicadas. - El directorio de configuración del sitio dentro del árbol de contenido — configuración y sobrescrituras del tema para el generador de sitios estáticos. - `docs/public/` — recursos estáticos que se copian textualmente al sitio final. - Un directorio por cada idioma adicional dentro del árbol de contenido — árboles de traducción que replican la estructura del idioma principal. Las páginas esbozo son marcadores de posición aceptables en un árbol de traducción. - `code/` — experimentos ejecutables alineados capítulo por capítulo con el texto. - `scripts/` — scripts de mantenimiento del repositorio, como la generación del sitemap, la verificación y la optimización de recursos. - El directorio del flujo de trabajo de CI — la canalización que construye y despliega el sitio. El material nuevo va bajo el directorio de contenido. Las entradas de navegación y de la barra lateral se declaran en el archivo de configuración del sitio, nunca se infieren únicamente de la ubicación del archivo. ## Ver y comprobar la web en local con los comandos del proyecto Trabaja a través de los puntos de entrada de los propios scripts del proyecto en lugar de invocar directamente las herramientas subyacentes, para que todo el mundo ejecute la misma canalización. Un sitio de documentación de esta forma expone un pequeño conjunto fijo de ellos: - `npm install` — instalar dependencias. - `npm run dev` — servidor de desarrollo con optimización de recursos. - `npm run dev:fast` — servidor de desarrollo que omite la optimización de recursos, para un arranque mucho más rápido. - `npm run build` — producir la salida publicable. - `npm run preview` — servir la salida construida exactamente como será publicada. - `npm run verify` — comprobaciones de consistencia en todo el repositorio. - `npm run assets:optimize` — comprimir y convertir imágenes. Usa la variante rápida de desarrollo mientras editas el texto, donde la optimización de imágenes no cambia nada de lo que estás mirando. Usa `build` seguido de `preview` cuando necesites ver la salida exactamente como será publicada. `verify` es la barrera descrita en la siguiente parte, y `assets:optimize` se ejecuta después de añadir imágenes para que los originales grandes nunca lleguen al sitio publicado. ## Actualizar el menú de cada idioma y comprobar antes de publicar - Mantén cada cambio acotado a la tarea que tienes entre manos. No reescribas documentos o configuraciones no relacionados mientras pasas por ellos. - Prefiere añadir material de curso nuevo bajo el directorio de contenido antes que reestructurar el material que ya existe. - Registra las páginas nuevas en la configuración de navegación y de la barra lateral cuando las añadas. - Cuando se añade, mueve o renombra una página, actualiza la barra lateral de cada árbol de idioma que la replique, no solo la del idioma principal. Un árbol de traducción que se queda atrás produce una entrada muerta o una página inexistente. - Ejecuta el comando de verificación antes de hacer push siempre que se haya tocado la configuración, el tema o los scripts de build. Un push publica el sitio, así que una construcción sin verificar lo rompe en público. ## Crear diagramas con fórmulas en LaTeX y pasarlos a SVG Las figuras de estilo académico con composición matemática real se crean como código fuente, no se dibujan a mano: 1. Escribe el diagrama como un documento independiente en un lenguaje de diagramas vectoriales — por ejemplo, un documento standalone de LaTeX que use un paquete de estilo TikZ. Copia el estilo de una figura que ya exista en el repositorio en lugar de inventar uno nuevo. 2. Compila el código fuente con un motor de LaTeX que admita las fuentes que utilizas, y después convierte el PDF resultante a SVG con un conversor de PDF a SVG. Ambos pasos son herramientas de línea de comandos, así que cualquier figura puede reconstruirse a partir de su fuente en cualquier momento. 3. Mantén tanto el archivo fuente como el SVG generado en el mismo directorio `images/`, junto al capítulo que los usa, para que la figura siga siendo reproducible. 4. Referencia el SVG generado desde la página markdown mediante una ruta relativa. Mantén un único estilo visual en todas las figuras: cajas de esquinas redondeadas con un relleno muy claro y un trazo gris oscuro, un único estilo de punta de flecha, una fuente de cuerpo que coincida con la del texto y delimitadores de matemáticas en línea para los símbolos. ## Escribir con voz de clase paciente, no con tono de charla - Escribe los capítulos como material de tutorial y de clase, no como notas de referencia escuetas. - Mantén una voz de clase guiada: conversacional, paciente y orientada a los problemas. Las expresiones que le entregan al lector el siguiente paso — «Empecemos por la intuición», «Mirémoslo desde otro ángulo», «Lo que este paso significa es…», «El verdadero problema es…» — son bienvenidas, mientras el tono se mantiene serio y preciso. - No caigas en un fraseo charlatán, de asistente ni en el lenguaje casual de internet. El registro objetivo es el de un capítulo de libro de texto pulido. - Dosifica el ritmo de los párrafos para que puedan leerse en voz alta o trabajarse en solitario. Si un párrafo no puede seguirse a velocidad de lectura, divídelo. ## Explicar todo el razonamiento y no escribir frases de relleno La profundidad y la economía conviven: explica toda la cadena de razonamiento y no gastes ni una palabra en nada que quede fuera de esa cadena. - Explica de forma progresiva — primero la intuición, luego la definición formal, luego el código o la práctica. - Da el contexto y la razón por la que un paso es necesario. No comprimas un capítulo en una simple lista de resultados. - Elimina el relleno de guía. Una frase que anuncia una explicación en lugar de darla («un ejemplo hará esto más intuitivo») se borra, y el ejemplo o la fórmula se presentan directamente. - Di cada cosa una sola vez. No reformules el mismo punto con otras palabras. - Sustituye los matizadores vagos por afirmaciones causales precisas. Los sustitutos metafóricos («esto es aproximadamente equivalente a…») y los conectores evasivos solo pertenecen a un primer borrador. - Evita las frases resumen tipo eslogan que comprimen un mecanismo en una cadena pegadiza. Enuncia en su lugar el mecanismo concreto. - Evita las listas de errores paralelos que suenan a máquina («la consulta era demasiado amplia, ninguna comparación de precios, nivel de stock incorrecto, parámetro incorrecto»). Describe el proceso y muestra cómo un estado erróneo temprano se propaga a las acciones posteriores. - Evita el patrón de contraste «no A, sino B»; se lee como indirecto. Enuncia la afirmación positiva y después explica por qué se sostiene. ## Ordenar las ideas para que cada paso nuevo llegue con su motivo - Sigue la línea causal. No des vueltas alrededor del mismo punto resumiéndolo, reformulándolo y luego contrastándolo. Escribe en el orden en el que la idea cambia realmente: aparece una nueva capacidad o configuración, esta cambia el entrenamiento o el objeto del problema, y eso hace posible o inevitable una nueva formulación. - Al abrir un concepto nuevo, prefiere la forma «ahora que existe X, el sistema hace Y, así que Z se vuelve posible (o necesario)». - Abre una sección conectando con lo que el lector ya conoce y luego nombra el nuevo problema que esa sección resuelve. - No hagas referencias a capítulos anteriores a menos que la referencia sea necesaria para la frase inmediatamente siguiente. - Da a cada paso conceptual una transición. Nunca saltes directamente de una definición a una fórmula, un término, un algoritmo o una conclusión; di por qué la siguiente idea es necesaria antes de introducirla. - No escribas páginas de estilo enciclopédico que solo enumeren definiciones. Una definición llega después de su motivación y va seguida de una interpretación. - Deja que los párrafos vayan de la pregunta a la respuesta. Una sección bien construida suele seguir este ritmo: ejemplo familiar → tensión o confusión → herramienta formal → ejemplo resuelto → conclusión. ## Mostrar un ejemplo conocido antes de la fórmula y explicar cada símbolo - Antes de introducir una fórmula o un algoritmo, enuncia el problema que resuelve; solo entonces muestra la notación. - Mantén una fórmula junto a su significado: explica cada símbolo importante y después reformula la fórmula entera en lenguaje llano. - Recurre a una escena concreta antes que a una abstracción. Montajes pequeños y familiares — una tarea de control de equilibrado de un péndulo, un bandido multibrazo, la generación de texto, una tarea de juego, una elección cotidiana — deben hacer que un concepto se sienta necesario antes de que se le ponga nombre. - Incluye derivaciones pequeñas en lugar de afirmar resultados, y mantén el texto orientado a quien aprende en todo momento. - Escribe los términos técnicos en el idioma principal del texto siempre que exista un equivalente establecido, en lugar de dejar la palabra inglesa prestada sin traducir. Conserva un término en inglés solo cuando sea un acrónimo estándar o cuando el título del capítulo lo exija, y explícalo en su primer uso. - Usa una única palabra fija por concepto en todo el curso. Un sinónimo que va cambiando de un capítulo a otro se lee, para quien aprende, como un segundo concepto. ## Usar secciones cortas con títulos y empezar cada commit con feat:, fix: u otra etiqueta - Usa secciones cortas con encabezados explícitos en lugar de largas tiradas de texto sin dividir. - Usa la negrita con moderación, para marcar un giro conceptual — nunca como decoración. - Usa kebab-case para las rutas bajo el directorio de contenido. - Prefiere rutas basadas en directorios con un `index.md` dentro, para que un tema pueda crecer hasta ocupar varias páginas sin cambiar su URL. - Usa Conventional Commits en cada cambio: `feat:`, `fix:`, `docs:`, `chore:`, y así sucesivamente.