High Priority Airflow-Core Doc Updates for 3.0.0 Release

[cmarteepants]

🎯 Goals

This issue tracks the reorganization and cleanup of the Airflow documentation for the 3.0 release. 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

📋 Task Breakdown

This issue is an umbrella to coordinate 3.0 docs work. Tasks can be broken into smaller issues or PRs that reference this one. We have prioritized changes that will have the most impact for new users and improve first impressions and usability.

❗High Priority

• Revamp Overview to better convey what Airflow, its value prop, and when it's the right tool
• Refresh core tutorials for approachability:
  • Airflow Fundamentals
  • Working with TaskFlow API
  • Building a Simple Data Pipeline
  • Object Storage
• Improve the "UI Guide" to reflect the new UI
  • Replace outdated screenshots (tracked below)
  • New screenshots to reflect new layout and features
  • Screenshots for new features (e.g DAG Versioning)
  • Terminology if anything changed (e.g. "Assets", "Watchers")
  • Gif(s) would be really cool (but is only a nice to have)

🖼️ Update Screenshots for 3.0

We need to replace 2.x screenshots with ones that reflect the Airflow 3.0 UI — in both light and dark mode.

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

Current pages that need updated screenshots:

• Overview
• Fundamental Concepts
• Building a Running Pipeline
• Add Tags for UI Filtering
• Managing Connections
• Managing Variables
• Setup and Teardown
• Email Configuration
• UI Overview
• Architecture Overview
• DAGs
• DAG Runs
• Dynamic Task Mapping
• Data-Aware Scheduling
• Airflow GitHub README
• Define Extra Links
• Customize UI
• Using params in Trigger UI Form
• Add Owner Links to DAG: Issue Re-implement support for DAG Owner Links #49247

🤝 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.0 docs genuinely great — and we can’t do it without community help. 💜

[potiuk]

Nice! It's great to think of the UX for the docs of ours :) We often miss it.