Documentation Overhaul

User documentation has to be reorganized and updated.

The main README.md links to Getting_Started.rst, which among other things links to:

• Quickstart
• CLI
• CLI usage examples
• Tutorial

The problems:

• Each of these is actually a tutorial. They cover CLI client, CLI repo, and advanced repo (repository_tool).
• The CLI client is not covered very well.
• Tutorial.py is actually a detailed repository creation tutorial, so it should be renamed something like ‘Advanced Repository Tutorial’
• Advanced client is not covered here (client/updater.py). There are some links and references in Tutorial.py about this, but that’s not where they belong since that’s really a repository tutorial, and they are wrong / outdated anyway. An unlinked-to tuf/client/README.md provides some instructions related to updater.py, but they need to be reviewed and linked to from Getting Started.
• Tutorial.py’s client section is bad / out of date:
  • It talks about a repository example created in tuf/README.md, but that file has no real contents, so we need to delete it.
  • It links to a document (tuf/client_setup_and_repository_example.md) that talks about using basic_client.py, which no longer exists. That document should also be deleted. Any valuable copy should be moved to tuf/client/README.md.
  • Client Setup and Test TUF Locally sections should be merged and clarified. (“To test the repository we’ve just created, we need to connect to it…”)

My current opinion is that we should move to having three tutorials instead of the many docs above:

• QUICKSTART, talking about the CLI client and repo, with these additions:
  • a note that these quickstart instructions will use the basic command-line interface, and that much more flexibility is available in “these advanced tutorials for repository_tool.py and updater.py”, with links (to the docs that are currently TUTORIAL.md and tuf/client/README.md).
  • a bit more about the CLI client than it currently has
• Advanced Repository Tutorial – largely, the contents of TUTORIAL.md
• Advanced Client Tutorial – what’s currently in tuf/client/README.md, updated and expanded a bit

We should also probably move those three docs to docs directory.

Miscellaneous other corrections:

• CLI client instructions should point out that it is necessary to run repo.py --init first, since that’s actually what sets up the client directory…
• There’s at least one missing cd-to-client-directory instruction in the CLI client instructions.

[trishankatdatadog]

Oh, you mean the pseudocode steps in English in that README, not the actual code itself, got it

[lukpueh]

I also still stand by my idea of using doctest. It’s actually something I’d like to play around with, because I also want to use it for in-toto (https://github.com/in-toto/in-toto/issues/276).

@awwad, let me know what you think and if I should help out, e.g. by taking over #775.