kaxil commented on code in PR #49098:
URL: https://github.com/apache/airflow/pull/49098#discussion_r2039695057


##########
airflow-core/docs/tutorial/fundamentals.rst:
##########
@@ -18,208 +18,163 @@
 
 
 
-Fundamental Concepts
+Airflow Fundamentals
 ====================
+Welcome to world of Apache Airflow! In this tutorial, we'll guide you through 
the essential concepts of Airflow, helping
+you understand how to write your first DAG. Whether you're familiar with 
Python or just starting out, we'll make the
+journey enjoyable and straightforward.
 
-This tutorial walks you through some of the fundamental Airflow concepts,
-objects, and their usage while writing your first DAG.
+What is a DAG?
+--------------
+At its core, a DAG is a collection of tasks organized in a way that reflects 
their relationships and dependencies. It's
+like a roadmap for your workflow, showing how each task connects to the 
others. Don't worry if this sounds a bit complex;
+we'll break it down step by step.
 
 Example Pipeline definition
 ---------------------------
-
-Here is an example of a basic pipeline definition. Do not worry if this looks
-complicated, a line by line explanation follows below.
+Let's start with a simple example of a pipeline definition. Although it might 
seem overwhelming at first, we'll explain
+each line in detail.
 
 .. exampleinclude:: /../src/airflow/example_dags/tutorial.py
     :language: python
     :start-after: [START tutorial]
     :end-before: [END tutorial]
 
-It's a DAG definition file
---------------------------
-
-One thing to wrap your head around (it may not be very intuitive for everyone
-at first) is that this Airflow Python script is really
-just a configuration file specifying the DAG's structure as code.
-The actual tasks defined here will run in a different context from
-the context of this script. Different tasks run on different workers
-at different points in time, which means that this script cannot be used
-to cross communicate between tasks. Note that for this
-purpose we have a more advanced feature called :doc:`/core-concepts/xcoms`.
-
-People sometimes think of the DAG definition file as a place where they
-can do some actual data processing - that is not the case at all!
-The script's purpose is to define a DAG object. It needs to evaluate
-quickly (seconds, not minutes) since the scheduler will execute it
-periodically to reflect the changes if any.
-
+Understanding the DAG Definition File
+-------------------------------------
+Think of the Airflow Python script as a configuration file that lays out the 
structure of your DAG in code. The actual
+tasks you define here run in a different environment, which means this script 
isn't meant for data processing. It's main
+job is to define the DAG object, and it needs to evaluate quickly since the 
DAG File Processor checks it regularly for
+any changes.
 
 Importing Modules
 -----------------
-
-An Airflow pipeline is just a Python script that happens to define an
-Airflow DAG object. Let's start by importing the libraries we will need.
+To get started, we need to import the necessary libraries. This is a typical 
first step in any Python script.
 
 .. exampleinclude:: /../src/airflow/example_dags/tutorial.py
     :language: python
     :start-after: [START import_module]
     :end-before: [END import_module]
 
+|
 
-See :doc:`/administration-and-deployment/modules_management` for details on 
how Python and Airflow manage modules.
+For more details on how Python and Airflow handle modules, check out
+:doc:`/administration-and-deployment/modules_management`.
 
-Default Arguments
------------------
-We're about to create a DAG and some tasks, and we have the choice to
-explicitly pass a set of arguments to each task's constructor
-(which would become redundant), or (better!) we can define a dictionary
-of default parameters that we can use when creating tasks.
+Setting Default Arguments
+-------------------------
+When creating a DAG and its tasks, you can either pass arguments directly to 
each task or define a set of default
+parameters in a dictionary. The latter approach is usually more efficient and 
cleaner.
 
 .. exampleinclude:: /../src/airflow/example_dags/tutorial.py
     :language: python
     :dedent: 4
     :start-after: [START default_args]
     :end-before: [END default_args]
 
-For more information about the BaseOperator's parameters and what they do,
-refer to the :py:class:`airflow.models.baseoperator.BaseOperator` 
documentation.
-
-Also, note that you could easily define different sets of arguments that
-would serve different purposes. An example of that would be to have
-different settings between a production and development environment.
+|
 
+If you want to dive deeper into the parameters of the BaseOperator, take a 
look at the documentation for
+:py:class:`airflow.models.baseoperator.BaseOperator` documentation.

Review Comment:
   It won't work right but once @ashb 's PR: 
https://github.com/apache/airflow/pull/47357 is merged, we should change this 
to:
   
   ```suggestion
   :py:class:`airflow.sdk.BaseOperator` documentation.
   ```
   
   



-- 
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]

Reply via email to