Best Practices for Developers Contributing to AI For Beginners: A Complete Guide

Contributors to Microsoft's AI For Beginners should follow strict repository organization, notebook style conventions, dependency management via environment.yml, translation workflows, and pull request etiquette to maintain a stable, beginner-friendly curriculum.

The microsoft/AI-For-Beginners repository serves as one of the most popular open-source AI curricula on GitHub, blending Jupyter notebooks, lesson markdown, and a Vue-based quiz application. Whether you're fixing a typo, adding a new lesson, or translating content, following the established best practices for developers ensures your contributions integrate smoothly and preserve the learning experience for thousands of beginners worldwide.

Repository Layout and Folder Organization

The AI For Beginners curriculum follows a strict top-level folder structure that separates content by purpose. Adhering to this layout prevents tangled dependencies and makes navigation intuitive for learners.

Required Top-Level Folders

• lessons/ — Core curriculum modules organized by topic (1-Intro, 2-History, 3-NeuralNetworks, etc.)
• examples/ — Standalone demo scripts for absolute beginners
• etc/quiz-app/ — Vue.js quiz application source code
• translations/ — Language-specific lesson packs (e.g., translations/es/, translations/zh/)

As documented in [README.md](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md), this separation lets learners navigate the curriculum logically and enables maintainers to add new lessons or translations without breaking existing content.

Lesson Structure Standards for AI For Beginners

Every lesson must follow a consistent three-part structure to ensure predictable learning flow. This convention is enforced throughout the lessons/ directory and documented in the main README.

Required Lesson Components

1. Pre-reading markdown file (README.md) — Theory and links to external resources
2. Executable Jupyter notebook(s) — Hands-on code in PyTorch and/or TensorFlow
3. Optional lab/ sub-folder — Additional practice exercises

When creating a new lesson, scaffold it following this pattern:

# Create the lesson folder matching the existing numbering scheme

mkdir -p lessons/5-NLP/22-NewTopic

# Add the markdown scaffold with proper headings

cat > lessons/5-NLP/22-NewTopic/README.md <<'EOF'

# New Topic: Sentiment Analysis with Transformers

This lesson introduces fine-tuning BERT for sentiment classification.

## Theory

<!-- Add links to MS Learn or external articles -->

## Notebook

- **PyTorch:** [SentimentBERT.ipynb](SentimentBERT.ipynb)
- **TensorFlow:** [SentimentBERT_TF.ipynb](SentimentBERT_TF.ipynb)
EOF

# Copy an existing notebook as a template

cp lessons/5-NLP/18-Transformers/TransformersPyTorch.ipynb \
   lessons/5-NLP/22-NewTopic/SentimentBERT.ipynb

Always update the curriculum table in [README.md](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) around line 83 when adding or removing lessons.

Notebook Style Guidelines for AI For Beginners Contributors

The Jupyter notebooks in AI For Beginners are the primary learning vehicle. Following these style conventions ensures beginners can execute code step-by-step without confusion.

Notebook Best Practices

• Clear hierarchical headings — Use markdown headings (#, ##, ###) to structure content
• Inline comments for every non-trivial code block — Explain why, not just what
• Self-contained cells — Avoid hidden state; each cell should run independently
• Exact dependency versions — Pin packages in environment.yml to prevent version drift

The [environment.yml](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file at repository root defines all Python dependencies. When adding new libraries:

1. Add the package with explicit version to environment.yml
2. Test the notebook in a fresh conda environment
3. Verify execution on Binder or GitHub Codespaces

# Create fresh environment from pinned dependencies

conda env create -f environment.yml -n ai4beg-test
conda activate ai4beg-test

# Validate notebook execution

jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb

Dependency Management in AI For Beginners

All Python dependencies are centralized in [environment.yml](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml). This single source of truth simplifies setup for contributors and guarantees reproducibility across platforms.

When modifying dependencies:

• Add new packages with explicit version constraints (e.g., torch==2.0.0)
• Never commit requirements.txt files in lesson folders
• Test locally before submitting PRs

This centralized approach ensures that Binder, GitHub Codespaces, and local conda installs all produce identical environments for learners.

Translation Workflow for AI For Beginners Localization

The AI For Beginners project supports multiple languages through a structured translation system integrated with automated CI pipelines.

Translation Folder Structure

Place new language packs under translations/<lang-code>/ mirroring the English lesson hierarchy exactly:

translations/
├── es/          # Spanish

│   └── lessons/
│       └── 5-NLP/
│           └── 22-NewTopic/
│               └── README.md   # Translated from English

├── zh/          # Chinese

└── ...

Translation Best Practices

• Preserve file names and folder layout — The Co-op Translator CI pipeline depends on path matching
• Translate only content files — Do not translate code outputs or notebook execution results
• Maintain heading structure — Keep #, ## hierarchy identical for automated TOC generation

# Example: Adding Spanish translation for a new lesson

cd translations/es/lessons/5-NLP/22-NewTopic
cp ../../../../../../lessons/5-NLP/22-NewTopic/README.md README.md

# Edit README.md with translated content, preserving all markdown structure

The CI system automatically detects new translation files and updates language badges in the main README.

Quiz App Integration Standards

The Vue.js quiz application in etc/quiz-app/ provides interactive assessments for each lesson. Changes to lesson content may require corresponding quiz updates.

Quiz App Maintenance Steps

1. Update JSON quiz files in etc/quiz-app/src/assets/quizzes/ when adding new questions
2. Run linting with npm run lint to maintain code style
3. Local testing with npm run serve before deployment

cd etc/quiz-app

# Add new question to existing quiz file

jq '.questions += [{
  "question": "What does BERT stand for?",
  "options": [
    "Bidirectional Encoder Representations from Transformers",
    "Binary Encoding Recurrent Transformer"
  ],
  "answer": 0
}]' src/assets/quizzes/nlp.json > tmp && mv tmp src/assets/quizzes/nlp.json

# Validate code style

npm run lint

# Test UI functionality locally

npm run serve

The quiz app deploys to Azure Static Web Apps; these validation steps prevent runtime errors in production.

Pull Request Etiquette for AI For Beginners

Following proper PR workflow ensures efficient review and avoids merge conflicts in this high-traffic repository.

PR Requirements

Checklist Item	Implementation
Single logical change per PR	Don't combine typo fixes with new lessons
Fork-based workflow	Create feature branches on your fork, not the main repo
Template compliance	Use the appropriate template from [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md)
CLA signature	Microsoft CLA-bot will prompt automatically; required before merge

The [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) file categorizes contributions into:

• Typo fixes — Minimal review, fast merge
• Lesson updates — Technical review required
• Translation additions — Language consistency check

Testing and Validation Procedures

All contributions must pass local validation before submission to prevent breaking the learning pipeline.

Required Testing Steps

For notebook changes:

conda activate ai4beg
jupyter notebook

# Execute all cells in the modified notebook; expect no errors

For quiz app changes:

cd etc/quiz-app
npm run serve

# Verify UI renders correctly and new questions function

For documentation changes:

• Render markdown preview to check link validity
• Verify curriculum table updates in README.md

Documentation Consistency Requirements

Maintain the [README.md](https://github.com/microsoft/AI-For-Beginners/blob/main/README.md) as the single source of truth for project navigation.

Required README Updates

• Curriculum table — Add/remove entries when lesson structure changes
• "Key Files" section — Keep file descriptions current
• Setup instructions — Reflect any environment.yml modifications

These updates ensure learners and contributors always have accurate project orientation.

Summary

Following these best practices for developers in AI For Beginners maintains curriculum quality and contribution velocity:

• Repository layout — Use lessons/, examples/, etc/quiz-app/, translations/ exclusively
• Lesson structure — Always provide README markdown, Jupyter notebook(s), and optional lab folder
• Notebook style — Self-contained cells, clear comments, pinned dependencies via environment.yml
• Translations — Mirror English hierarchy exactly under translations/<lang-code>/
• Quiz app — Update JSON files, run npm run lint and npm run serve for validation
• Pull requests — Single logical change, fork workflow, CLA signature, template compliance
• Testing — Local notebook execution and quiz app verification before submission

Frequently Asked Questions

What folder should I use when adding a new lesson to AI For Beginners?

Place new lessons under the appropriate topic folder in lessons/ using the existing numbering scheme (e.g., lessons/5-NLP/22-NewTopic/). The first number indicates the curriculum section, and the second number provides lesson ordering. Always update the curriculum table in README.md when adding lessons.

How do I add a new Python dependency to AI For Beginners?

Add the package with exact version to the root [environment.yml](https://github.com/microsoft/AI-For-Beginners/blob/main/environment.yml) file, not to individual lesson folders. Test your notebook in a fresh conda environment created from this file to ensure reproducibility. The centralized dependency management supports Binder, Codespaces, and local development equally.

Can I translate AI For Beginners content into a new language?

Yes. Create a new folder under translations/ using the standard language code (e.g., translations/de/ for German), then mirror the exact folder structure and file names from the English lessons/ directory. The Co-op Translator CI pipeline will automatically detect and process your translations if the structure matches precisely.

What testing is required before submitting a pull request to AI For Beginners?

Execute all modified notebooks locally with jupyter notebook to verify error-free cell execution. For quiz app changes, run npm run lint and npm run serve in etc/quiz-app/ to validate UI functionality. These steps prevent breaking the learning experience for other contributors and thousands of learners.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}