cmarteepants opened a new issue, #45649:
URL: https://github.com/apache/airflow/issues/45649
### Body
## Epic
Overhaul the Airflow documentation structure and content for the 3.0 release
to improve usability, clarity, and consistency.
## Background
We're reorganizing and updating the docs to:
- Make them more intuitive for both new and experienced users.
- Separate the quickstart from installation details.
- Clearly highlight core concepts, common how-to guide and advanced usage.
- Align with a new docs style guide to ensure consistent tone, structure and
formatting
**Proposed Docs Structure** (High-Level)
1. Introduction
2. Quickstart
3. Installation
4. Core Concepts & Basic Usage
5. Common How-to Guides
6. Advanced Usage & Best Practices
7. Deployment & Administration
8. Reference
9. Tutorials & Examples
10. Community & Contributing
## Goals
1. **Restructure** existing content into the new hierarchy.
2. **Rewrite** or **streamline** key pages (Quickstart, Installation, Core
Concepts) for clarity.
3. **Document** any new or changed features specific to Airflow 3.0.
4. **Apply** consistent style/formatting using the agreed-upon style guide.
5. **Provide** placeholders or notes where full rewrites aren't feasible
before launch.
## Scope & Deliverables
- **Create new folders / ToC entries** reflecting the new structure.
- **Migrate old content** from the current documentation site into the new
structure.
- **Revise** top-priority pages (Quickstart, Installation, Core Concepts) to
align with 3.0.
- **Mark** outdated or deprecated content for removal or archival.
- **Review & update** references to deprecated features.
- **Incorporate style guide** best practices, including consistent tone,
headings and formatting.
- **Add placeholders** for topics we can't fully document right now (with an
invitation for community help!)
## Style Guide
A style guide will be created to maintain consistency across the docs.
High-level draft guidelines:
- **Tone:** Friendly yet professional.
- **Structure:** Short paragraphs, active voice, bullet lists where possible.
- **Code & Examples:** Realistic examples, tested snippets.
- **Links & References:** Descriptive link text.
- **Terminology:** Use official Airflow terms and versions correctly.
## Tasks & Checklist
Below is a suggested breakdown of tasks. Each item can be further broken
down or moved into individual issues that reference this epic.
Planning & Setup
**1. Planning & Setup**
- [ ] Finalize the new docs outline
- [ ] Finalize the style guide
- [ ] Validate local build environment for docs
**2. Audit Existing Pages**
- [ ] Create a master spreadsheet or confluence page with a list of all
current doc pages (title, URL/file path)
- [ ] Tag each page with "Keep", "Rewrite", "Merge" or "Remove"
- [ ] Identify new or changed features in Airflow 3.0 that need coverage
**3. Create New File Structure**
- [ ] Create folders/sections for each high-level heading (Introduction,
Quickstart, etc.)
- [ ] Move existing docs into corresponding sections with minimal edits
- [ ] Update cross-links where possible
**4. Rewrite High-Priority Sections**
- [ ] Quickstart: Provide a simple, minimal path to bootstrap an Airflow
project and get Airflow running with a first DAG
- [ ] Installation: Separate from Quickstart, describe multiple install
methods
- [ ] Core Concepts: Clarify DAGs, tasks, operators, assets, scheduling,
and any 3.0 changes
**5. Apply Style Guide & Clean Up**
- [ ] Ensure headings, bullet points, and code formatting adhere to the
style guide
- [ ] Add warnings/notes for deprecated features
- [ ] Remove or consolidate redundant explanations
**6. Placeholder & Advanced Topics**
- [ ] Create stubs for Advanced Usage, Best Practices, Deployment
Administration, etc.
- [ ] Invite community contributions for in-depth guides or
operator-specific docs
**7. Final Review & Launch**
- [ ] Test-build the docs in a staging environment
- [ ] Solicit feedback from the community and QA testers
- [ ] Fix broken links, remove "TODO" placeholders
- [ ] Merge & publish as the 3.0 documentation set
## Contributing
Interested in helping? Comment below or create a pull request referencing
this epic. We welcome contributions like:
- Revising a specific doc page
- Adding examples or tutorials
- Fixing typos or broken links
- Providing diagrams or visuals
We want to make Airflow 3.0 docs as user-friendly as possible, and community
input is invaluable!
### 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]
