📘 Airflow 3 Docs

🎯 Goals

This issue tracks the reorganization and cleanup of the Airflow documentation for Airflow 3, and is meant to be implemented incrementally over time. Our goals:

• Improve usability, clarity, and consistency across the docs
• Ensure examples are compatible with Airflow 3.0
• Update screenshots for both light and dark UI modes

✍️ Draft Style Guide

We’re working on a lightweight style guide to help keep the documentation consistent and welcoming.

Initial Guidelines:

• Tone: Friendly but professional
• Structure: Short paragraphs, active voice, bullet lists where helpful
• Code & Examples: Realistic and tested
• Links: Use Descriptive Text (avoid "click here")
• Images: Images that are added should have alt-text for accessibility reasons
• Terminology: Stick to official Airflow terms

When uploading screenshots:

• Add dark mode images to airflow-core/docs/img/ui-dark
• Add light mode image to airflow-core/docs/img/ui-light
• Use the same filename so we can easily support theme switching later

📋 Task Breakdown

This issue is an umbrella to coordinate Airflow 3 docs work. Tasks can be broken into smaller issues or PRs that reference this one.

❗High Priority

• High Priority Airflow-Core Doc Updates for 3.0.0 Release #45649
• Airflow Task SDK Docs #49627

✅ New User Content

This section focuses on improvements that will have the most impact for new users and improve first impressions and usability.

🟡 Medium Priority

• Rewrite "Concepts" section:
  • Need to be split into subtasks
  • The current page is dense and assumes context. It's critical for helping users form a mental model.
    • Suggestions:
      • Use simpler language and analogies
      • Add diagrams
      • Highlight what's new in 3.0 is different (Fetching DAGs via DAG Bundles, Asset-centric execution)
• Expand "Quickstart" into a meta page:
  • One-page “Quickstart Overview” with a minimal example that shows off Airflow’s superpowers
  • Existing Quickstart mostly just bootstraps a dev instance
• Reorganize Side Nav:In Progress
  • The current structure assumes prior knowledge
  • We’d like a cleaner top-down flow that mirrors a new user’s journey

🟢 Nice-to-Have

• Create new tutorials:
  • Asset-Centric Authoring (@asset)
  • Event-driven scheduling with Asset Watchers
  • (Open to other ideas!)
• Clarify Installation Options:
  • Current section can be confusing
  • We could add a small decision tree to help folks pick between Astro, MWAA, GCC, Breeze, Docker, K8s, etc
  • Need to verify that the installation instructions are valid

🤝 How to Contribute

We welcome contributions of all sizes!

You can:

• Comment here or open a PR referencing this issue
• Tackle a doc page rewrite
• Improve examples or tutorials
• Fix typos, broken links, formatting
• Add visuals or diagrams

The goal is to make Airflow 3 docs genuinely great — and we can’t do it without community help. 💜

Committer

• I acknowledge that I am a maintainer/committer of the Apache Airflow project.