DOC: revise quickstart and reorganize tutorials:

- correctly frame the CLI's current state as a tutorial toy.
- provide a friendlier quickstart that puts what it's doing into
  perspective and guides you to next steps.
- provide a better sense of what each tutorial/quickstart doc is
  for.
- make the getting started page slightly more friendly.

Signed-off-by: Sebastien Awwad <sebastien.awwad@gmail.com>

docs/GETTING_STARTED.rst

@@ -1,9 +1,8 @@
 Getting Started
 ---------------
 
+- `Overview of TUF <OVERVIEW.rst>`_
 - `Installation <INSTALLATION.rst>`_
-- `Contributors <CONTRIBUTORS.rst>`_
-- `Quickstart <QUICKSTART.md>`_
-- `CLI <CLI.md>`_
-- `CLI Usage Examples <CLI_EXAMPLES.md>`_
-- `Tutorial <TUTORIAL.md>`_
+- Beginner Tutorials (using the basic command-line interface): `Quickstart <QUICKSTART.md>`_; `CLI Tutorial <CLI.md>`_; `CLI Further Examples <CLI_EXAMPLES.md>`_
+- `Advanced Tutorial <TUTORIAL.md>`_
+- `Guidelines for Contributors <CONTRIBUTORS.rst>`_

docs/QUICKSTART.md

@@ -1,21 +1,44 @@
 # Quickstart #
 
-The CLI requires a few dependencies and C extensions that can be installed with
-`pip install securesystemslib[crypto,pynacl]`.
+In this quickstart tutorial, we'll use the basic TUF command-line interface
+(CLI), which includes the `repo.py` script and the `client.py` script, to set
+up a repository with an update and metadata about that update, then download
+and verify that update as a client.
+
+Unlike the underlying TUF modules that the CLI uses, the CLI itself is a bit
+bare-bones.  Using the CLI is the easiest way to familiarize yourself with
+how TUF works, however.  It will serve as a very basic update system and use
 
 ----
-The following is a basic workflow in four steps:
 
-**Step (1)** - Initialize a repo.  The `tufrepo`, `tufkeystore`, and
-`tufclient` directories are created in the current working directory.
+**Step (0)** - Make sure TUF is installed
+
+See the [installation instructions for TUF](docs/INSTALLATION.rst).
+The TUF CLI makes use of some crypto dependencies, so please include the
+optional `pip install securesystemslib[crypto,pynacl]` step.
+
+
+**Step (1)** - Create a basic repository and client
+
+The following command will set up a basic update repository and basic client
+that knows about the repository.  `tufrepo`, `tufkeystore`, and
+`tufclient` directories will be created in the current directory.
+
 ```Bash
 $ repo.py --init
 ```
-Four sets of keys are created in the `tufkeystore` directory and metadata
-is initiated in the `tufrepo` and `tufclient` directories.
 
-**Step (2)** - Add a target file to the repo.  The file size and hashes of
-the target file are also written to the Targets metadata file.
+Four sets of keys are created in the `tufkeystore` directory.  Initial metadata
+about the repository is created in the `tufrepo` directory, and also provided
+to the client in the `tufclient` directory.
+
+
+**Step (2)** - Add an update to the repository.
+
+We'll create a target file that will later be delivered as an update to clients.
+Metadata about that file will be created and signed, and added to the
+repository's metadata.
+
 ```Bash
 $ echo 'Test file' > testfile
 $ repo.py --add testfile
@@ -38,21 +61,38 @@ tufrepo/
 
     3 directories, 11 files
 ```
-The new file `testfile` is added and metadata is updated in the `tufrepo` directory.
+
+The new file `testfile` is added to the repository, and metadata is updated in
+the `tufrepo` directory.  The Targets metadata (`targets.json`) now includes
+the file size and hashes of the `testfile` target file, and this metadata is
+signed by the Targets role's key, so that clients can verify that metadata
+about `testfile` and then verify `testfile` itself.
+
 
 **Step (3)** - Serve the repo
+
+We'll host a toy http server containing the `testfile` update and the
+repository's metadata.
+
 ```Bash
 $ cd "tufrepo/"
+$ python3 -m http.server 8001
+
+# or, if you are using Python2:
 $ python -m SimpleHTTPServer 8001
 
-or with Python 3...
-$ python3 -m http.server 8001
 ```
 
-**Step (4)** - Fetch a target file from the repo.  The client downloads
-any required metadata and the requested target file.
+**Step (4)** - Obtain and verify the `testfile` update on a client.
+
+The client can request the package `testfile` from the repository.  TUF will
+download and verify metadata from the repository as necessary to determine
+what the trustworthy hashes and length of `testfile` are, then download
+the target `testfile` from the repository and keep it only if it matches that
+trustworthy metadata.
+
 ```Bash
-$ cd "tufclient/"
+$ cd "../tufclient/"
 $ client.py --repo http://localhost:8001 testfile
 $ tree
 .
@@ -75,11 +115,35 @@ $ tree
 
     5 directories, 11 files
 ```
-client.py verified metadata from the server and downloaded content. The client has now verified and obtained `testfile`.
-The scope of TUF ends here.
+
+Now that a trustworthy update target has been obtained, an updater can proceed
+however it normally would to install or use the update.
 
 ----
 
-See [CLI.md](CLI.md) and [CLI_EXAMPLES.md](CLI_EXAMPLES.md) to learn about the
-other supported CLI options.  A [tutorial](TUTORIAL.md) is also available, and
-intended for users that want more control over the repo creation process.
+### Next Steps
+
+TUF provides functionality for both ends of a software update system, the
+**update provider** and the **update client**.
+
+`repo.py` made use of `tuf.repository_tool`'s functionality for an update
+provider, helping you produce and sign metadata about your updates.
+
+`client.py` made use of `tuf.client.updater`'s client-side functionality,
+performing download and the critical verification steps for metadata and the
+update itself.
+
+You can look at [CLI.md](CLI.md) and [CLI_EXAMPLES.md](CLI_EXAMPLES.md) to toy
+with the TUF CLI a bit more.  After that, try out using the underlying modules
+for a great deal more control.  The more detailed [TUF Tutorial](TUTORIAL.md)
+shows you how to use them.
+
+Ultimately, a sophisticated update client will use or re-implement those
+underlying modules.  The TUF design is intended to play well with any update
+workflow.
+
+Please provide feedback or questions for this or other tutorials, or
+TUF in general, by checking out
+[our contact info](https://github.com/theupdateframework/tuf#contact), or
+creating [issues](https://github.com/theupdateframework/tuf/issues) in this
+repository!