BasPH commented on PR #26486: URL: https://github.com/apache/airflow/pull/26486#issuecomment-1254126046
> Have you actually tried to find out that Airflow has a task flow using the current documentation? Actually, yes I do. I understand perfectly fine there's a taskflow API. I think you're not understanding the _context_. As I said, this is the first page a reader will see when opening the documentation. This introduces a narrative: what is Airflow, what can it do, why would I use Airflow? Etc. The main page is **not** the place to show a user all possible ways to write a DAG. Not everybody is a full time Python engineer and most people that will read this page are just starting to understand what Airflow is about, so examples should be as simple as possible. Have you ever had a training, read a book, or heard a conference talk where multiple concepts were introduced in the first minute? No. People process new information in steps, you can't introduce 10 new concepts in one go. You explain new concepts gradually. For this reason, I think it's a bad idea to show both a "regular" operator and a "taskflow" operator. Assuming the reader is new to Airflow, there's already a DAG, operators, and dependencies. You want to display as few as possible concepts to introduce an example. The "regular" operators easily show what it's running: BashOperator runs Bash, PythonOperator runs Python. TaskFlow is different from regular operators, it uses decorators and I don't think it's immediately clear why you have to call a TaskFlow task, i.e. `airflow()` instead of `airflow`, plus the changed example uses both the regular and taskflow style operators. This requires additional cognitive load. The introduction to Airflow should focus on what Airflow is and display an absolute bare-minimum example of what Airflow code might look like. It should not demonstrate all possible ways to write a DAG. -- 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]
