doc: consider re-adding a "quickstart" document

[lukpueh]

Supersedes #1006

Description of issue or feature request:
#1790 removes QUICKSTART.md because it is severely outdated. The new client and repo examples should be a good replacement to quickly get users familiar with python-tuf and are also easy to discover (e.g. via main README and main menu on RTD).

Still, there might be merit in better framing these examples or adding additional examples as a "quick start"-documentation (note: this is also a silver criteria for the cii badgeapp).

Current behavior:

• no explicit "quick start" documentation

Expected behavior:

• consider adding quick start documentation or better frame existing documentation

[joshuagl]

I think the ideal place for quick start documentation for a library like python-tuf is the developer documentation on RTD.

[MVrachev]

Also, we should keep in mind that we have the examples/ folder with some great examples.
I think we would need a quickstart document if we are going to showcase the usage of a TUF CLI.
I see that in examples/client.py we do provide a CLI for the client.
Maybe a small QUICKSTART.md document showcasing how to use the examples/client.py CLI and a reference to the examples/basic_repo.py could be enough.

[lukpueh]

Also, we should keep in mind that we have the examples/ folder with some great examples. I think we would need a quickstart document if we are going to showcase the usage of a TUF CLI. I see that in examples/client.py we do provide a CLI for the client. Maybe a small QUICKSTART.md document showcasing how to use the examples/client.py CLI and a reference to the examples/basic_repo.py could be enough.

Exactly! That's what I meant with "...or better frame existing documentation"

[mhmohona]

Hello @lukpueh, I would like to work on this issue.

I have checked the previous quickstart guide we had and got an idea of it. I see we already have Installation guide, so it is just enough to refer to this page, isnt it?

For outline of quickstart page, considering beginner audience as my target audience, I have following in my mind -

Quickstart with TUF

1. Introduction to TUF

• Brief explanation of what TUF is and its purpose
• Mention the security benefits it provides (e.g., resilience against key compromises, prevention of mix-and-match attacks)

2. Installing TUF

(link of existing installation guide)

3. Using the TUF CLI Tools

• Introduce the CLI tools (repo.py, client.py) and their purpose
• Step-by-step instructions for a basic workflow using the CLI:
  1. Initializing a TUF repository
  2. Adding a target file to the repository
  3. Serving the repository (using a simple HTTP server)
  4. Fetching a target file from the repository as a client

4. Understanding the CLI Output

• Explain the output and directory structure created by the CLI tools
• Briefly mention the different metadata files and their roles

5. Next Steps

• Mention that the CLI tools are a convenient way to get started with TUF
• For more advanced use cases and integrating TUF into applications, suggest exploring the TUF Python library
• Provide links to the complete TUF documentation and other resources

What do you think about it? How can I improve it?

[lukpueh]

Introduce the CLI tools (repo.py, client.py) and their purpose

Those cli tools don't exist anymore. You could take a look the existing repository and client examples and see how they could be used for a quick start guide.

[mhmohona]

Thank you for correcting me @lukpueh! I have submitted a PR. Will you please have a look at it #2640?

[jku]

It's not really a "quickstart" for integrating python-tuf, but I think we could build something around the examples that a newcomer would benefit from:

• repository app to run a repository
• uploader to add artifacts to the repository
• and finally client to securely download the artifacts from the repository

Each of these already has their own README but I can see benefit in a single page that creates a story around the whole thing and documents how to run all three.