cmarteepants opened a new issue, #49738:
URL: https://github.com/apache/airflow/issues/49738
### Body
# 📘 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**
- [x] High Priority Airflow 3.0.0 doc updates #45649
- [ ] Task SDK docs: #49627
### ✅ <ins>Update Content</ins>
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
- [x] I acknowledge that I am a maintainer/committer of the Apache Airflow
project.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
