Improve introductory docs

[adityasaky]

in-toto has grown quite a bit in the last few years and a lot of the work happening in the project is in distinct repositories that aren't easy to find or grok. This has meant that people who are unfamiliar with the project have difficulty coherently understanding the project as a whole. Even folks who are acquainted with in-toto are often surprised to learn about other capabilities. For example, one person I was talking to in the supply chain security space knew of in-toto for its attestation framework and was surprised to learn of the main specification with in-toto layouts etc. Now that the main specification has reached v1 and the attestation framework has also matured, I think we should spend some time on introducing people to in-toto as a whole.

Updates to in-toto.io

The website is now quite outdated. Until recently, it didn't even call out the attestation framework. I propose revamping the website and making the content of https://in-toto.io/in-toto/ much more concrete, possibly with examples.

in-toto 101

In addition, it might be helpful to provide slightly more detailed posts that explore in-toto attestations, layouts, and how they come together. We lack quite a bit here as our existing material may not be geared to newcomers.

Videos?

Finally, I think it might be helpful to have short intro videos, likely no more than three or four, that provide an overview of in-toto, how and where it's used, and how to get started with adopting in-toto. I wonder if the CNCF can help us out here?

And more?

I've listed some initial ideas but there's room for more! For example, we could further flesh out in-toto/friends and turn them into user stories / adoption blog posts on the CNCF blog.

[jufantozzi]

Mostly unrelated to this overhaul, and for the lack of a better place to point this out, the link that points to the stable spec, in the page below:

https://in-toto.io/in-toto/

as in

You can read more about in-toto’s internals in our latest or stable specification.

is broken due to the referenced link pointing to a .pdf file, when it actually is a .md, as in

https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md

I tried to find the repository containing that documentation but maybe that isn't open?

[adityasaky]

@jufantozzi thanks for pointing that out! Opened a PR to fix that: in-toto/in-toto.io#21

[jbogarthyde]

I have opened a new umbrella issue for immediate ways to improve user documentation -
https://github.com/in-toto/docs/issues/85

[Ayush9026]

@adityasaky sir i want to raise PR for this issue.