Best practices in Google Colab for sharing with non-technical teams#

In teams where technical and non-technical profiles coexist, it is common for the technical team to develop notebooks in Google Colab for periodic processes: monthly reports, data analysis, recurring tasks. The problem arises when these processes require periodic execution with small variations — a different month, another department, a new input file — and the responsibility of running them always falls on the technical team.

This dynamic creates unnecessary overhead: the technical team becomes a bottleneck for tasks that, with the right structure, anyone could run autonomously.

The solution is to structure notebooks so that non-technical teams can execute them on their own, without risk of altering the logic and without needing to understand the code. This notebook presents the best practices I have applied in my experience and also serves as a downloadable template you can adapt to your own processes.

Process documentation#

Every shared notebook must start with clear documentation. It is the first impression the user gets and determines whether they can use it without help. The documentation should include: what the process does, what input data it needs (files and location), what output data it generates (files and location) and step-by-step instructions for running it.

Below is an example of documentation for a report generation process.

Process: Monthly departmental report.

Objective: Generate a monthly summary from daily operations data for a department.

Input data: CSV file in My Drive/reports/data/ named data_YYYY_MM.csv (e.g., data_2026_02.csv).

Output data: CSV report in My Drive/reports/results/ named report_DEPARTMENT_YYYY_MM.csv (e.g., report_sales_2026_02.csv).

Instructions:

  1. Run the first code cell and authorize Google Drive access.

  2. Modify the parameters (year, month and department) in the Parameters cell.

  3. From the menu, select Runtime > Run all (or Ctrl+F9).

  4. Wait for completion. Progress will be shown in the last cell.

Imports and Drive initialization#

This block is placed as the first code cell for two reasons:

  1. Google Drive requires user authorization. If this cell comes first, the user grants permission immediately and the rest of the notebook runs without interruptions.

  2. Early error detection: if there is a problem with the Drive connection or any dependency, it is caught before executing any logic.

# @title Default title text
import pandas as pd
from datetime import datetime
from pathlib import Path

from google.colab import drive

drive.mount("/content/drive")
print("Drive connected successfully.")

Mounted at /content/drive
Drive connected successfully.

Parameters (non-technical team)#

This is the only cell the non-technical team should modify. Parameters are presented as Colab form fields using the #@param syntax, which generates visual controls (text fields, dropdowns, etc.) that make editing easy without touching code.

An important tip: use closed lists (#@param ["option1", ...]) instead of free text whenever possible. This prevents typos and ensures valid values. image.png

#@title Report parameters
year = 2026 #@param {type:"integer"}
month = 2 #@param {type:"integer"}
department = "sales" #@param ["sales", "marketing", "operations"]

Technical variables (technical team)#

The following cells contain internal configurations that the non-technical team does not need to see or modify. In Google Colab, cells are hidden using #@title as the first line and setting the cell view to form (cellView: form). This collapses them visually, showing only the title.

To configure this:

  • Add #@title Descriptive title as the first line of the code cell.

  • Click the three dots on the cell > Form view.

  • Or set "cellView": "form" in the cell metadata.

#@title Technical variables (do not modify)
BASE_DIR = Path("/content/drive/MyDrive/reports")
INPUT_DIR = BASE_DIR / "data"
OUTPUT_DIR = BASE_DIR / "results"

INPUT_FILE = INPUT_DIR / f"data_{year}_{month:02d}.csv"
OUTPUT_FILE = OUTPUT_DIR / f"report_{department}_{year}_{month:02d}.csv"

REQUIRED_COLUMNS = ["date", "department", "category", "amount"]

Processing logic (technical team)#

The processing logic is also hidden. All functionality is encapsulated in functions with descriptive names. This makes maintenance easier for the technical team and prevents the non-technical team from accidentally modifying the logic.

#@title Processing functions (do not modify)

def validate_params(year, month, department):
    """Validates that parameters are correct."""
    errors = []
    if not (2020 <= year <= 2030):
        errors.append(f"Year out of range: {year}")
    if not (1 <= month <= 12):
        errors.append(f"Invalid month: {month}")
    if department not in ["sales", "marketing", "operations"]:
        errors.append(f"Unrecognized department: {department}")
    return errors


def load_data(path):
    """Loads the CSV file and validates columns."""
    if not path.exists():
        raise FileNotFoundError(
            f"File not found: {path}\n"
            f"Please verify the file exists in Google Drive."
        )
    df = pd.read_csv(path)
    missing = [c for c in REQUIRED_COLUMNS if c not in df.columns]
    if missing:
        raise ValueError(f"Missing columns in file: {missing}")
    return df


def process_data(df, department):
    """Filters and aggregates data by department."""
    df_filtered = df[df["department"] == department].copy()
    if df_filtered.empty:
        raise ValueError(
            f"No data found for department: {department}"
        )
    summary = (
        df_filtered
        .groupby("category")
        .agg(
            total=("amount", "sum"),
            count=("amount", "count"),
            average=("amount", "mean"),
        )
        .reset_index()
        .sort_values("total", ascending=False)
    )
    return summary


def save_report(df, path):
    """Saves the report to the specified path."""
    path.parent.mkdir(parents=True, exist_ok=True)
    df.to_csv(path, index=False)

Execution#

This cell runs the full process. It remains visible so the non-technical team can verify progress and results. Log messages indicate each step.

print(f"{'=' * 50}")
print(f"Report: {department} - {year}/{month:02d}")
print(f"{'=' * 50}")
print()

# Step 1: Validate parameters
print("▶ Validating parameters...")
errors = validate_params(year, month, department)
if errors:
    for error in errors:
        print(f"  ✗ {error}")
    raise SystemExit("Process stopped due to parameter errors.")
print("  ✓ Parameters valid.")

# Step 2: Load data
print(f"▶ Loading data from: {INPUT_FILE.name}")
df = load_data(INPUT_FILE)
print(f"  ✓ {len(df)} records loaded.")

# Step 3: Process data
print(f"▶ Processing data for '{department}'...")
summary = process_data(df, department)
print(f"  ✓ {len(summary)} categories in summary.")

# Step 4: Save report
print(f"▶ Saving report to: {OUTPUT_FILE.name}")
save_report(summary, OUTPUT_FILE)
print(f"  ✓ Report saved successfully.")

print()
print(f"{'=' * 50}")
print("Process completed.")
print(f"{'=' * 50}")

==================================================
Report: sales - 2026/02
==================================================

▶ Validating parameters...
  ✓ Parameters valid.
▶ Loading data from: data_2026_02.csv
  ✓ 300 records loaded.
▶ Processing data for 'sales'...
  ✓ 4 categories in summary.
▶ Saving report to: report_sales_2026_02.csv
  ✓ Report saved successfully.

==================================================
Process completed.
==================================================

Naming conventions#

One of the most important best practices is using fixed or programmatic format names for files and folders. This prevents human errors and makes automation easier.

Names to avoid#

Example

Problem

report january.csv

Space in name, no year, free-form text

Data_Sales_2026.CSV

Inconsistent casing, uppercase extension

my report (final) v2.csv

Special characters, manual versioning

Time execution considerations#

Google Colab has time limits worth knowing about:

  • Free sessions disconnect after ~90 minutes of inactivity or 12 hours of continuous execution.

  • Colab Pro offers longer sessions but is still limited.

Recommendations:

  1. Save intermediate results: If the process is long, save partial results to Drive after each stage. If the session disconnects, progress is not lost.

  2. Progress indicators: Use print() or tqdm so the user knows the process is still running.

  3. Batch processing: If data is very large, process in chunks instead of loading everything into memory.

  4. Error handling: Wrap execution in try/except blocks to save partial results on failure.

Best practices summary#

  1. Document the process at the beginning of the notebook.

  2. Place imports and Drive connection as the first code cell.

  3. Separate editable parameters in a visible cell with Colab forms (#@param).

  4. Hide technical variables and processing logic using #@title and form view.

  5. Use a visible execution cell with progress messages.

  6. Use fixed or programmatic file names, never free-form text.

  7. Account for Colab time execution limits.

  8. Prefer closed lists over free text fields for parameters.

References#

Anterior: Prompt Engineering: Technical Skill or Scam?   Siguiente: Buenas prácticas en Google Colab para compartir con equipos no técnicos