Cómo documentar un Notebook con Copilot en Fabric

Documentar un Notebook suele ser la tarea que siempre se deja para el final — y la primera en olvidarse. Aun así, es lo que permite que otra persona, o tu propio "yo" de dentro de tres meses, entienda qué hace el código y por qué. Copilot en Microsoft Fabric resuelve buena parte de este problema: puede explicar el código celda a celda, en lenguaje natural, y escribir la documentación en Markdown a partir de lo que ya existe en el Notebook. Veamos cómo hacerlo con un ejemplo sencillo de PySpark.

Requisitos previos

• Un workspace de Microsoft Fabric en una capacidad de pago F2 o superior (desde abril de 2025, Copilot dejó de exigir capacidades grandes como F64).
• La configuración de administrador "Users can use Copilot and other features powered by Azure OpenAI" habilitada en el tenant.
• Un Notebook de Fabric con al menos una celda de código.
• Conocimientos básicos de PySpark y de cómo ejecutar celdas en un Notebook.

Paso 1: Abrir Copilot en el Notebook

Abre tu Notebook en Fabric. En la barra de herramientas superior, haz clic en el botón Copilot para abrir el panel de conversación (el chat pane) en el lado derecho de la pantalla. En este panel escribirás las peticiones y leerás las respuestas. Si el botón no aparece, casi siempre significa que la capacidad no es F2 o superior, o que la configuración de Copilot todavía no se ha habilitado — conviene comprobarlo con quien administra el tenant antes de continuar.

Paso 2: Preparar el código que se va a documentar

Para el ejemplo usaremos un caso pequeño y realista: leer una tabla de ventas y calcular el total por región. Pega este código en una celda y ejecútalo, para que Copilot tenga contexto sobre los datos y sobre el resultado que producen.

from pyspark.sql.functions import sum

df = spark.read.table("vendas")
resumo = (df.groupBy("regiao")
            .agg(sum("valor").alias("total_vendas"))
            .orderBy("total_vendas", ascending=False))
display(resumo)

Fíjate en que el código está limpio y con nombres claros. No es casualidad: cuanto más legible sea el código, más precisa será la explicación que Copilot pueda dar.

Paso 3: Pedir a Copilot que explique el código

En el panel de Copilot, escribe una petición sencilla y directa. Un buen ejemplo es:

Explica, en español, qué hace cada celda de este notebook.

Copilot lee el contenido de las celdas y responde con una explicación en lenguaje natural: qué tabla se lee, qué agregación se realiza y qué representa el resultado final. Es la forma más rápida de entender un Notebook que heredaste de un compañero o que no tocas desde hace meses. Si quieres centrarte en una sola parte, selecciona la celda y pide "explica solo la celda seleccionada" — Copilot limitará su respuesta a ese bloque.

Consejo: cuanto más específica sea la petición ("explica qué representa la columna valor"), más útil será la respuesta. Las preguntas vagas generan respuestas vagas.

Paso 4: Generar e insertar la documentación en Markdown

Una vez que entiendas el código, pide a Copilot que convierta la explicación en documentación reutilizable:

Escribe documentación en Markdown para este notebook, con un título y una sección por paso.

El resultado suele ser parecido a esto:

## Resumen de ventas por región

Este notebook lee la tabla `vendas`, agrega el `valor` total
por `regiao` y muestra el resultado ordenado de mayor a
menor total.

1. Importa la función de agregación `sum`.
2. Lee la tabla `vendas` en un DataFrame.
3. Agrupa por `regiao` y suma `valor`.
4. Muestra el resumen con `display`.

Crea una nueva celda de tipo Markdown en la parte superior del Notebook y pega ahí el texto generado. Revisa siempre lo que Copilot escribió: te da un excelente punto de partida, pero el contexto de negocio — qué es la tabla "vendas", de dónde vienen los datos, con qué frecuencia se actualizan — solo lo conoces tú y debes añadirlo.

Verificar el resultado

Para confirmar que todo está bien, comprueba tres cosas. Primero, la celda Markdown debe aparecer con formato, con el título destacado y la lista numerada legible. Segundo, la explicación tiene que coincidir con lo que el código hace realmente — léela con atención, porque Copilot puede equivocarse. Tercero, y lo más importante: ¿puede un compañero que nunca ha visto el Notebook entender su objetivo solo con la documentación? Si alguna frase es vaga o incorrecta, ajusta la petición (por ejemplo, "sé más específico sobre el origen de los datos") y genérala de nuevo.

Conclusión

En pocos minutos pasaste de un Notebook sin ningún contexto a un Notebook explicado y documentado en Markdown, sin escribir una sola línea de documentación a mano. Un siguiente paso natural es pedir a Copilot que comente el propio código o que sugiera nombres de variables más claros, para que el Notebook sea aún más fácil de mantener. Y tú — ¿cuál será el primer Notebook olvidado que por fin vas a documentar?