HandcartCactus opened a new issue, #62298: URL: https://github.com/apache/airflow/issues/62298
### What do you see as an issue? <img width="1638" height="862" alt="Image" src="https://github.com/user-attachments/assets/12b7fc5b-3fd8-4d17-8116-32febf935206"; /> 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 `<THE_REGULAR_SYNTAX>` 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) -- 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]
