Documentation full review

docs/features.md

@@ -1,6 +1,6 @@
 ## Design based on **FastAPI**
 
-**Typer** is the little sibling of <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>.
+**Typer** is <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>'s little sibling.
 
 It follows the same design and ideas. If you know FastAPI, you already know **Typer**... more or less.
 
@@ -46,7 +46,7 @@ The resulting CLI apps created with **Typer** have the nice features of many "pr
 * Automatic command and sub-command structure handling (you will see more about sub-commands in the Tutorial - User Guide).
 * Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit <kbd>TAB</kbd> and get the options of sub-commands. *
 
-!!! note * Autocompletion
+!!! note "* Autocompletion"
     For the autocompletion to work on all shells you also need to add the dependency `click-completion`.
 
     Just that. And **Typer** does the rest.

docs/index.md

@@ -24,23 +24,23 @@
 
 ---
 
-Typer is library to build <abbr title="command line interface, programs executed from a terminal">CLI</abbr> applications that users love using and developers love creating. Based on Python 3.6+ type hints.
+Typer is library to build <abbr title="command line interface, programs executed from a terminal">CLI</abbr> applications that users will love using and developers will love creating. Based on Python 3.6+ type hints.
 
-**Typer** is the little sibling of <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>. And it's intended to be the FastAPI of CLIs.
+**Typer** is <a href="https://fastapi.tiangolo.com" target="_blank">FastAPI</a>'s little sibling. And it's intended to be the FastAPI of CLIs.
 
 The key features are:
 
 * **Intuitive to write**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
 * **Easy to use**: It's easy to use for the final users. Automatic help commands, and (optional) automatic completion for all shells.
 * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
 * **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**.
-* **Grow large**: Grow in complexity as much as you want create arbitrarily complex trees of commands and groups sub-commands, with options and arguments.
+* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups sub-commands, with options and arguments.
 
 ## Requirements
 
 Python 3.6+
 
-Typer stands on the shoulders of a giant. Internally it uses <a href="https://click.palletsprojects.com/" target="_blank">Click</a>, that's the only dependency.
+Typer stands on the shoulders of a giant. Its only internal dependency is <a href="https://click.palletsprojects.com/" target="_blank">Click</a>.
 
 ## Installation
 
@@ -112,7 +112,7 @@ Options:
 
 ## Example upgrade
 
-The previous example was the extreme in terms of simplicity.
+This was the simplest example possible.
 
 Now let's see one a bit more complex.
 
@@ -280,14 +280,14 @@ For a more complete example including more features, see the <a href="https://ty
 
 Typer uses <a href="https://click.palletsprojects.com/" target="_blank">Click</a> internally. That's the only dependency.
 
-But you can install extras:
+But you can also install extras:
 
-* <a href="https://pypi.org/project/colorama/" target="_blank"><code>colorama</code></a>: and Click will automatically use it to make sure colors always work correctly, even in Windows.
-    * Then you can use any tool you want to output colors in all the systems, including the integrated `typer.style()` and `typer.secho()` (provided by Click).
+* <a href="https://pypi.org/project/colorama/" target="_blank"><code>colorama</code></a>: and Click will automatically use it to make sure your terminal´s colors always work correctly, even in Windows.
+    * Then you can use any tool you want to output your terminal's colors in all the systems, including the integrated `typer.style()` and `typer.secho()` (provided by Click).
     * Or any other tool, e.g. <a href="https://pypi.org/project/wasabi/" target="_blank"><code>wasabi</code></a>, <a href="https://github.com/erikrose/blessings" target="_blank"><code>blessings</code></a>.
 * <a href="https://github.com/click-contrib/click-completion" target="_blank"><code>click-completion</code></a>: and Typer will automatically configure it to provide completion for all the shells, including installation commands.
 
-You can install `typer` with `colorama` and `click-completion` with `pip3 install typer[all]`.
+You can install `typer` with `colorama` and `click-completion` with `pip install typer[all]`.
 
 ## Other tools and plug-ins
 
@@ -296,7 +296,7 @@ Click has many plug-ins available that you can use. And there are many tools tha
 For example:
 
 * <a href="https://github.com/click-contrib/click-spinner" target="_blank"><code>click-spinner</code></a>: to show the user that you are loading data. A Click plug-in.
-    * * There are several other Click plug-ins at <a href="https://github.com/click-contrib" target="_blank">click-contrib</a> that you can explore.
+    * There are several other Click plug-ins at <a href="https://github.com/click-contrib" target="_blank">click-contrib</a> that you can explore.
 * <a href="https://pypi.org/project/tabulate/" target="_blank"><code>tabulate</code></a>: to automatically display tabular data nicely. Independent of Click or typer.
 * etc... you can re-use many of the great available tools for building CLIs.
 

docs/tutorial/first-steps.md

@@ -158,11 +158,7 @@ Hello Camila Gutiérrez
 
 ## What is a **CLI option**
 
-Here we will use the word **CLI option** to refer to **CLI parameters** passed to the CLI application with a specific name. Because they have a name they don't depend on the order. By default they are *optional* (not *required*).
-
-They are a bit different from **CLI arguments** that you already created.
-
-If you go to your terminal and type:
+Here we will use the word **CLI option** to refer to *CLI parameters* passed to the CLI application with a specific name. For example, if you go to your terminal and type:
 
 ```bash
 ls ./myproject --size
@@ -174,16 +170,26 @@ ls ./myproject --size
 * `./myproject` is a *CLI argument*.
 * `--size` is an optional *CLI option*.
 
-A *CLI option* like `--size` doesn't depend on the order like a *CLI argument*.
-
 The program knows it has to show the size because it sees `--size`, not because of the order.
 
+A *CLI option* like `--size` doesn't depend on the order like a *CLI argument*.
+
 So, if you put the `--size` *before* the *CLI argument*, it still works:
 
 ```bash
 ls --size ./myproject
 ```
 
+The main visual difference between a *CLI option* and and a *CLI argument* is that the *CLI option* has `--` prepended to the name, like in "`--size`".
+
+A *CLI option* doesn't depend on the order because it has a predefined name (here it's `--size`). This is because the CLI app is looking specifically for a literal `--size` parameter or "flag", with that specific "name" (here the specific name is "`--size`"). The CLI app will check if you typed it or not, it will be actively looking for `--size` even if you didn't type it (to check if it's there or not).
+
+In contrast, the CLI app is not actively looking for the *CLI argument* with a text "`./myproject`", it has no way to know if you would type `./myproject` or `./mysuperawesomeproject` or anything else. It's just waiting to get whatever you give it. The only way to know that you refer to a specific *CLI argument* is because of the order. The same way that it knows that the first *CLI argument* was the `name` and the second was the `lastname`, but if you mixed the order, it wouldn't be able to handle it.
+
+Instead, with a *CLI option*, the order doesn't matter.
+
+Also, by default, a *CLI option* is *optional* (not *required*).
+
 !!! tip
     In this example above the *CLI option* `--size` is just a "flag", it's a boolean value, `True` or `False`.
 
@@ -260,9 +266,9 @@ both still show:
 Good day Ms. Camila Gutiérrez.
 ```
 
-## A **CLI option* with a value
+## A *CLI option* with a value
 
-Let's convert the `lastname` from a *CLI argument* to a *CLI option*:
+To convert the `lastname` from a *CLI argument* to a *CLI option*, give it a default value of `""`:
 
 ```Python hl_lines="4"
 {!./src/first_steps/tutorial005.py!}
@@ -290,6 +296,8 @@ Options:
 !!! tip
     Notice the `--lastname`, and notice that it takes a textual value.
 
+    A *CLI option* with a value like `--lastname` (contrary to a *CLI option* without a value, a `bool` flag, like `--formal` or `--size`) takes as its value whatever is at the *right side* of the *CLI option*.
+
 If you call it without a `--lastname`:
 
 ```bash
@@ -314,6 +322,9 @@ and it shows:
 Hello Camila Gutiérrez
 ```
 
+!!! tip
+    Notice that "`Gutiérrez`" is at the right side of `--lastname`. A *CLI option* with a value takes as its value whatever is at the *right side*.
+
 And as `--lastname` is now a *CLI option* that doesn't depend on the order, you can pass it before the name:
 
 ```bash

docs/tutorial/intro.md

@@ -17,7 +17,7 @@ And your editor (and Typer) will know that:
 * `formal` is a `bool` and is by default `False`.
 * `intro` is a `str`, and by default is `None`, so it's optional.
 
-These type hints are what gives you autocomplete in your editor and several other features.
+These type hints are what give you autocomplete in your editor and several other features.
 
 Typer is based on these type hints.
 
@@ -33,7 +33,7 @@ So you can come back and see exactly what you need.
 
 ## Run the code
 
-All the code blocks can be copied and used directly (they are actually tested Python files).
+All the code blocks can be copied and used directly (they are tested Python files).
 
 To run any of the examples, copy the code to a file `main.py`, and run it: