¿Qué es un Codelab?
Un Codelab (o "Laboratorio de Código") es un formato de tutorial interactivo y guiado que ofrece una experiencia de aprendizaje práctica y autoguiada. Aunque popularizado por Google para la enseñanza de código, el concepto se aplica a cualquier tema donde el aprendizaje se logra siguiendo instrucciones y ejecutando tareas para construir o completar un proyecto.
Están diseñados para que el usuario aprenda una nueva habilidad, plataforma, o proceso al:
En esencia, es un laboratorio de práctica autoguiado que se enfoca en el aprendizaje mediante la acción y la práctica inmediata (learning by doing).
Características Clave
Los Codelabs tienen estas características esenciales, sin importar el tema:
¿Para qué sirven?
Como formato de aprendizaje, los Codelabs son ideales para:
Para transformar un documento en un formato de Codelab interactivo y publicable, se necesita configurar el entorno con las siguientes herramientas esenciales:
Elemento | Descripción y Propósito |
1. Editor de Texto (Soporte Markdown) | El contenido de los Codelabs se escribe generalmente en formato Markdown (o a partir de un Google Doc). Se necesitará un editor robusto para escribir y estructurar tu tutorial. |
2. La Herramienta claat | claat (acrónimo de Codelab as a Tool) es la utilidad oficial de línea de comandos de Google. Su función principal es: |
3. Comprensión de Comandos de Consola | Dado que claat es una herramienta de línea de comandos, se necesitará un entendimiento básico de cómo usar la Terminal (o Símbolo del Sistema en Windows) para: |
La metadata de un Codelab es un bloque de información estructurada que describe los atributos clave del tutorial, como su título, descripción, autor, duración estimada, nivel de dificultad, tecnologías usadas, e idioma.
A continuación se presenta la estructura de la metada de un Codelab.
author: Author Name
summary: Summary of your codelab that is human readable
id: unique-codelab-identifier
categories: codelab,markdown
environments: Web
status: Published
feedback link: A link where users can go to provide feedback (Maybe the git repo)
analytics account: Google Analytics ID
Los metadatos constan de pares clave-valor de la forma "clave: valor". Las llaves no pueden contener dos puntos y los campos de metadatos separados deben estar separados por líneas en blanco.
En la actualidad, todos los valores deben estar en una línea. Todos los metadatos deben ir antes del título. Se pueden utilizar claves y valores arbitrarios; sin embargo, sólo lo siguiente será entendido por el renderizador:
Tipo de enlace | Ejemplo |
Formulario de Google Forms |
|
Issue de GitHub |
|
Enlace a encuesta personalizada |
|
Email directo |
|
Las secciones de un Codelab son los bloques estructurados que dividen el contenido en partes lógicas y secuenciales. Cada sección guía al lector a través del aprendizaje de forma clara, progresiva y práctica.
Una buena práctica es usar un título y subtítulo claros al inicio de cada sección. En una sección debe buscar una acción clara, una explicación y una verificación del resultado. Cada sección debe ser corta y enfocada en una sola tarea.
Las secciones más comunes en un Codelab pueden incluir:
Sección | Propósito |
🟢 Introducción | Presenta el tema, los objetivos y lo que aprenderá el usuario. |
🔧 Prerrequisitos | Lista conocimientos previos, software, hardware o cuentas necesarias. |
📋 Que se va a construir | Resume el producto o resultado final del Codelab (puede incluir una imagen). |
🛠️ Pasos guiados | Contienen las instrucciones detalladas paso a paso con texto, código, comandos y verificaciones. |
✅ Verificación / Resultado esperado | Muestra cómo saber si el paso se realizó correctamente. |
🧠 Desafíos opcionales | Actividades adicionales para ampliar lo aprendido. |
📚 Recursos adicionales | Enlaces externos, documentación, ejemplos relacionados. |
🗣️ Retroalimentación / Siguiente paso | Pide feedback o sugiere otros Codelabs relacionados. |
🏁 Conclusión | Resume lo aprendido y señala hacia posibles avances o aplicaciones. |
Markdown es un lenguaje de marcado ligero que te permite dar formato al texto (como negritas, cursivas o títulos) utilizando símbolos simples que se pueden escribir fácilmente. Es la forma en que se estructura todo el contenido de un Codelab. La idea de markdown es que el texto sea fácil de escribir y que al mismo tiempo se pueda convertir en HTML para mostrarlo con estilo en la web.
🧩 ¿Para qué se usa Markdown?
✅ Ventajas de Markdown
En la siguiente tabla se presenta un resumen de la sintaxis fundamental de Markdown, para incluir en un Codelab.
Elemento | Sintaxis Markdown | Ejemplo renderizado |
Título principal (H1) | # Título | Título |
Subtitulo (H2) | ## Subtítulo | Subtítulo |
Subtitulo (H3) | ### Subtítulo | Subtítulo |
Negrita |
| Texto en negrita |
Cursiva |
| Texto en cursiva |
Lista con viñetas | - Elemento o * Elemento | • Elemento |
Lista numerada | 1. Elemento | 1. Elemento |
Enlace |
| |
Citas |
| Nota: Recuerda que necesitas tener instalado Node.js versión 14 o superior. |
Una vez que se domina la estructura básica del Codelab, se puede enriquecer el contenido del tutorial con elementos multimedia y de código para mejorar la claridad y la experiencia del usuario.
Las imágenes son esenciales para mostrar resultados, pasos de interfaz o diagramas. La sintaxis de Markdown es simple, pero es importante tener en cuenta cómo se gestionan las rutas (rutas de archivo) de las imágenes.
Elemento | Sintaxis Markdown | Ejemplo |
Imágenes Locales |
|
|
Imágenes Web |
|
|
Aunque el Markdown estándar no soporta etiquetas nativas para videos incrustados, los Codelabs de Google están diseñados para reconocer una sintaxis especial que procesa y muestra videos de YouTube directamente en el tutorial. Esto es útil para proporcionar demostraciones visuales rápidas, introducciones o explicaciones complejas.
La sintaxis que utiliza el Codelab es similar a la de las imágenes, pero requiere la palabra clave youtube y la URL completa del video:
Propósito | Sintaxis Codelab | Ejemplo de Código |
Incrustar Video |
|
|
Los bloques de código son cruciales en los Codelabs, ya sea para mostrar fragmentos de código, comandos de terminal o salidas de consola. El uso de la sintaxis "cercas de código" (code fences) con el nombre del lenguaje mejora el resaltado de sintaxis (Syntax Highlighting).
Para crear un bloque de código, se usa tres comillas inversas (``` ```) al principio y al final, y se especifica el lenguaje inmediatamente después de las tildes de apertura.
Ejemplo | Sintaxis Markdown |
Hola Mundo en Javascript. Una sola línea de código | ```Javascript |
Hola Mundo en Python. Una sola línea de código | ```Python |
Ejemplo en Python. Varias líneas de código | ```Python |
Ejemplo Javascript:
console.log("Hola Mundo");
Ejemplo Python:
# Esto es un hola mundo
print("Hola Mundo")
Ejemplo Python:
# Sumar dos valores
a = int(input("Ingrese el valor de a "))
b = int(input("Ingrese el valor de b "))
c = a+b
print("El resultado es ", c)
Además de la sintaxis estándar de Markdown, los Codelabs de Google ofrecen etiquetas especiales para insertar funcionalidad avanzada, como botones que actúan como llamadas a la acción (CTA) y soporte completo para notación matemática.
Los botones son esenciales para guiar al usuario a un recurso externo o a la descarga de un archivo. Al igual que con los videos, los botones utilizan una sintaxis de Markdown específica que es reconocida por la herramienta claat.
Para la creación de un botón se utiliza la opción [button-text](URL)
Ejemplo: Un botón de accion para descargar Visual Studio Code
[Visual Studio Code](https://code.visualstudio.com/Download)
Para cualquier contenido técnico, científico o matemático, el formato Codelab permite incrustar ecuaciones utilizando el lenguaje LaTeX. Esto asegura que las fórmulas complejas se muestren de manera limpia y profesional, en lugar de como texto simple.
Las ecuaciones se insertan utilizando el símbolo de dólar ('$') para ecuaciones en línea y el doble símbolo de dólar ('$$') para ecuaciones en bloque (centradas).
A continuación se presenta un ejemplo de uso:
$$ x_{1,2}=\frac{-b \pm \sqrt{b^2-4ac}}{2a} $$
Claat es el acrónimo de Codelab as a Tool (Codelab como Herramienta) y es la utilidad oficial de línea de comandos desarrollada por Google. Es el motor que toma la documentación en formato Markdown (o Google Docs) y la transforma en el Codelab interactivo que se publica en la web.
El propósito de esta herramienta es crucial para el flujo de trabajo del Codelab:
Aunque existen varios comandos, para la creación y prueba de Codelabs solo son necesarios dos principales:
Comando | Función | Descripción |
claat export [archivo] | Generación Final | Convierte el archivo fuente (.md o ID de Google Doc) en una carpeta con el Codelab listo para ser publicado (HTML, CSS, JS). |
claat serve | Prueba Local | Inicia un servidor web temporal en la máquina local para que se pueda ver y probar el Codelab en tiempo real mientras se edita, generalmente en http://localhost:9090. |
Cuando se ejecuta el comando claat export, se crea el contenido web estático necesario para alojar el Codelab. El contenido web estático se crea en un directorio especificado por su "id" único y se puede ver localmente abriendo la página index.html.
Si has llegado hasta este punto, siguiendo el tutorial, has demostrado un excelente conocimiento de la Regresión Logística y sus aplicaciones.
Ahora estas en capacidad de aplicar la Regresión Logística para resolver problemas del mundo real. Solo vas a necesitar recoletar y preparar tus datos para comenzar a trabajar.
Este tutorial fue pensado para apoyar algunos conceptos de los cursos de Machine Learning, Procesamiento de Lenguaje Natural, Estadística III, Procesamiento Digital de Imágenes y Bioingenería, sin embargo, los conceptos desarrollados pueden ser extrapolados a diferentes aplicaciones y ramas del conocimiento
Al ser un tutorial tan corto, y si tienes poca experiencia en el campo, es posible que quieras profundizar en algunos conceptos adicionales que no se cubrieron en este tutorial. Algunos de estos temas son:
Cox, D. R. (1958). The regression analysis of binary sequences. Journal of the Royal Statistical Society: Series B (Methodological), 20(2), 215–242.