apache / apache/airflow

Quick Start Page Needs Some TLC, IMO

Open
#62,298 2 comments 0 reactions 0 assignees View on GitHub
kind:bug kind:documentation needs-triage
Dominant language
Python
Stars
46.9k
Forks
17.8k
Avg merge
2d 9h
Merged PRs (30d)
472

Description

### What do you see as an issue?

Image

Hey! Airflow user here. The quick start page is the most important documentation page of any project, and Airflow's needs some love. I'm volunteering to fix it, this issue will document some of my changes.

A quick start page is reflects the bare minimum required to install the project and get it running. See, for example, [pandas](https://pandas.pydata.org/docs/getting_started/index.html), [numpy](https://numpy.org/install/), or [jupyter](https://jupyter.org/install). There is no discussion of versions or extras or pinned dependencies. That goes somewhere else.

Specific Issues:
1. Grammar: "methods is" should be "methods are".
2. the "\` or \`\`uv\`\`" in the source file appears to be missing here, for reasons I don't understand.
3. The install command should be a copyable code block.
4. Beginners do not usually understand `[EXTRAS]`. They don't know that `EXTRAS` needs to be replaced with real values, and this page does not explain that the options are any of `async, graphviz, kerberos, memray, gunicorn, otel, statsd` or `all`. One could define a bash variable earlier in the code block called `EXTRAS` and refer to it here as `$EXTRAS`, but that is seriously overkill for a quick start page. A simple list will do, if you mention it at all.
5. Someone visiting the quick start page wants the most recent airflow version. If they wanted something else, they would be on a different page. Also, it's not clear to some users that AIRFLOW_VERSION needs to be replaced. It isn't wrapped in `` for a required replacement or set as a `$VARIABLE`. Like EXTRAS, this is a potential stumbling block. A simple `pip install apache-airflow` will download the most recent version by default. Requiring a pin here for the quick start page increases documentation maintenance surface area and makes life difficult for first timers (for little benefit).
6. `--constraint` is an uncommon flag, I have never seen it in any other project's quick start page. Discussion of reproducible builds probably belongs elsewhere, like the more detailed installation page. Generally speaking, all of the dependencies you need to get started *should* be in the `pyproject.toml` or `requirements.txt`.
7. See 5.
8. See 5 about variable syntax. If Airflow is going to tell people to reference PYTHON_VERSION on the quick start page, it might as well show them how to get it right up front, so people with less experience don't have to leave the page.
9. This example is for an outdated version of Airflow, which, as discussed, is probably not what people want to install when they visit a quick start page. I think a project should generally avoid this. See 5.
10. Discussion of how to use unsupported tools should probably be in a distinct section, and maybe not on the quick start page.
11. "convert these pins to whatever appropriate workflow and tool your project requires" is not quick start instructions.
12. (not labled) Calling out "just add `uv` to the beginning of the command" is almost certainly going to be missed by most users. Most people will be skimming for a code block. [`numpy` handles this by providing both commands explicitly.](https://numpy.org/install/)
13. (not labeled) Everything beneath this screenshot belongs in the more detailed installation page. Steps 4 and 5 can stay in the quick start page. Maybe a test command can stay too.
14. (not labeled) Python version compatibility goes in a full matrix in the main install page.

### Solving the problem

Move the existing documentation to a more detailed install page and replace this entire page with something far simpler.

### Anything else

_No response_

### Are you willing to submit PR?

- [x] Yes I am willing to submit a PR!

### Code of Conduct

- [x] I agree to follow this project's [Code of Conduct](https://github.com/apache/airflow/blob/main/CODE_OF_CONDUCT.md)

Contributor guide

Open the contributing guide

Research direction

Start by reading the current quick start page and the more detailed installation content, then inspect the referenced pyproject.toml or requirements.txt for the installation assumptions. Move detailed material out of the quick start page and simplify its commands and explanations so a beginner can install and run the latest Airflow version without unclear placeholders.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.