How to document a Notebook with Copilot in Fabric

João Barros 06 de July de 2026 4 min read

Documenting a Notebook is usually the task that always gets left for last — and the first one to be forgotten. Yet it is what lets someone else, or your own self three months from now, understand what the code does and why. Copilot in Microsoft Fabric solves much of this problem: it can explain the code cell by cell, in natural language, and write the documentation in Markdown based on what already exists in the Notebook. Let's see how to do it with a simple PySpark example.

Prerequisites

A Microsoft Fabric workspace on a paid capacity of F2 or higher (since April 2025, Copilot no longer requires large capacities such as F64).
The admin setting "Users can use Copilot and other features powered by Azure OpenAI" enabled in the tenant.
A Fabric Notebook with at least one code cell.
Basic knowledge of PySpark and how to run cells in a Notebook.

Step 1: Open Copilot in the Notebook

Open your Notebook in Fabric. On the top toolbar, click the Copilot button to open the chat pane on the right side of the screen. This pane is where you type your requests and read the responses. If the button doesn't appear, it almost always means the capacity is not F2 or higher, or that the Copilot setting hasn't been enabled yet — it's worth checking with whoever administers the tenant before moving on.

Step 2: Prepare the code to document

For the example, we'll use a small, realistic case: reading a sales table and calculating the total per region. Paste this code into a cell and run it, so that Copilot has context about the data and the result it produces.

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)

Notice that the code is clean and uses clear names. This is no accident: the more readable the code, the more accurate the explanation Copilot can give.

Step 3: Ask Copilot to explain the code

In the Copilot pane, write a simple, direct request. A good example is:

Explain, in English, what each cell of this notebook does.

Copilot reads the content of the cells and replies with a natural-language explanation: which table is read, which aggregation is performed and what the final result represents. It's the fastest way to understand a Notebook you inherited from a colleague or haven't touched in months. If you want to focus on just one part, select the cell and ask "explain only the selected cell" — Copilot will limit its answer to that block.

Tip: the more specific the request ("explain what the valor column represents"), the more useful the answer. Vague questions produce vague answers.

Step 4: Generate and insert the documentation in Markdown

Once you understand the code, ask Copilot to turn the explanation into reusable documentation:

Write Markdown documentation for this notebook, with a title and one section per step.

The result usually looks like this:

## Sales summary by region

This notebook reads the `vendas` table, aggregates the total
`valor` by `regiao` and shows the result ordered from the
highest to the lowest total.

1. Imports the `sum` aggregation function.
2. Reads the `vendas` table into a DataFrame.
3. Groups by `regiao` and sums `valor`.
4. Shows the summary with `display`.

Create a new Markdown cell at the top of the Notebook and paste the generated text there. Always review what Copilot wrote: it gives you an excellent starting point, but the business context — what the "vendas" table is, where the data comes from, how often it is refreshed — is something only you know and should add.

Checking the result

To confirm everything is fine, check three things. First, the Markdown cell should appear formatted, with the title standing out and the numbered list readable. Second, the explanation must match what the code actually does — read it carefully, because Copilot can make mistakes. Third, and most important: can a colleague who has never seen the Notebook understand its purpose from the documentation alone? If any sentence is vague or incorrect, adjust the request (for example, "be more specific about where the data comes from") and generate it again.

Conclusion

In just a few minutes, you went from a Notebook with no context at all to a Notebook that is explained and documented in Markdown, without writing a single line of documentation by hand. A natural next step is to ask Copilot to comment the code itself or to suggest clearer variable names, making the Notebook even easier to maintain. So — which forgotten Notebook are you finally going to document first?