:memo: Update and clarify first-steps tutorial

diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md
index 40c4d1ba33ed7066015f2ce424f0eda7a435d2ce..5b41bfc4a9156d9d5f59427a66df9abedcddcf03 100644 (file)
--- a/docs/tutorial/first-steps.md
+++ b/docs/tutorial/first-steps.md
@@ -148,7 +148,7 @@ https://example.com/items/foo
 !!! info
     A "path" is also commonly called an "endpoint" or a "route".
 
-Building an API, the "path" is the main way to separate "concerns" and functionalities.
+Building an API, the "path" is the main way to separate "concerns" and "resources".
 
 #### Operation
 
@@ -172,7 +172,7 @@ In the HTTP protocol, you can communicate to each path using one (or more) of th
 
 ---
 
-When building APIs, you normally use these specific HTTP methods to perform a specific operation.
+When building APIs, you normally use these specific HTTP methods to perform a specific action.
 
 Normally you use:
 
@@ -183,7 +183,7 @@ Normally you use:
 
 So, in OpenAPI, each of the HTTP methods is called an "operation".
 
-We are going to call them "operations" too.
+We are going to call them "**operations**" too.
 
 #### Define a path operation function
 
@@ -196,6 +196,17 @@ The `@app.get("/")` tells **FastAPI** that the function right below is in charge
 * the path `/`
 * using a <abbr title="an HTTP GET method"><code>get</code> operation</abbr>
 
+!!! info "`@decorator` Info"
+    That `@something` syntax in Python is called a "decorator".
+
+    You put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from).
+
+    A "decorator" takes the function below and does something with it.
+
+    In our case, this decorator tells **FastAPI** that the function below corresponds to the **path** `/` with an **operation** `get`.
+
+    It is the "**path operation decorator**".
+
 You can also use the other operations:
 
 * `@app.post()`
@@ -216,9 +227,15 @@ And the more exotic ones:
 
     The information here is presented as a guideline, not a requirement.
 
-    For example, when using GraphQL you normally perform all the operations using only `post`.
+    For example, when using GraphQL you normally perform all the actions using only `post`.
+
+### Step 4: define the **path operation function**
 
-### Step 4: define the path operation function
+This is our "**path operation function**":
+
+* **path**: is `/`.
+* **operation**: is `get`.
+* **function**: is the function below the "decorator" (below `@app.get("/")`).
 
 ```Python hl_lines="7"
 {!./src/first_steps/tutorial001.py!}
@@ -226,7 +243,7 @@ And the more exotic ones:
 
 This is a Python function. 
 
-It will be called by FastAPI whenever it receives a request to the URL "`/`".
+It will be called by **FastAPI** whenever it receives a request to the URL "`/`" using `GET`.
 
 In this case, it is an `async` function.
 
@@ -238,7 +255,8 @@ You could also define it as a normal function instead of `async def`:
 {!./src/first_steps/tutorial003.py!}
 ```
 
-To know the difference, read the section about [Concurrency and `async` / `await`](/async/).
+!!! note
+    If you don't know the difference, check the _"In a hurry?"_ section about <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` and `await` in the docs</a>.
 
 ### Step 5: return the content
 
@@ -250,4 +268,13 @@ You can return a `dict`, `list`, singular values as `str`, `int`, etc.
 
 You can also return Pydantic models (you'll see more about that later).
 
-There are many other objects and models that will be automatically converted to JSON.
+There are many other objects and models that will be automatically converted to JSON (including ORMs, etc). Try using your favorite ones, it's highly probable that they are already supported.
+
+
+## Recap
+
+* Import `FastAPI`.
+* Create an `app` instance.
+* Write a **path operation decorator** (like `@app.get("/")`).
+* Write a **path operation function** (like `def root(): ...` above).
+* Run the debugging server (like `uvicorn main:app --debug`).
\ No newline at end of file