search

in-toto / specification

Specification and other related documents.
https://in-toto.io
MIT License
39 stars 25 forks source link

would be nice to point to live website docs from README #15

Closed ultrasaurus closed 1 year ago

ultrasaurus commented 5 years ago

the website has some nice intro material -- would be nice to link from this repo, since I looked here first before discovering the website

ultrasaurus commented 5 years ago

I also found that going through the step by step guide at https://in-toto.engineering.nyu.edu/ was helpful in understanding the interaction. It would be nice to see one path laid out as a guide or tutorial -- maybe that exists somewhere and I just didn't find it.

lukpueh commented 5 years ago

Thanks for your feedback, @ultrasaurus! We've always used https://github.com/in-toto/in-toto as the (code) landing page to our project. But I can see how that might not be obvious to someone who browses any other repo under the in-toto organization. Maybe we should point to our website and/or the main repo in each repo's description. What do you think? At any rate, adding some more information to this repo's README would be nice indeed.

lukpueh commented 5 years ago

The layout web wizard was actually meant to guide a user through the creation of an in-toto layout without requiring too much previous knowledge or any additional instructions. But as your comment (and the feedback from beta testers) suggest, there are still some usability issues. I will reference your feedback on the corresponding issue page...

In the meanwhile, maybe you also want to take a look at these layout creation instructions?

ultrasaurus commented 5 years ago

@lukpueh thanks for the info. I think in general the docs lack contextual information and a strong narrative around a typical use case. Your "demo" looks like it is more of a tutorial and actually has the kind of content that I was looking for.

A little feedback on that -- in reading it, I would have been able to absorb the information more quickly if the "simple workflow" spelled out (e.g. with numbered list: checkin code, run tests, release software artifact).

Also, I keep forgetting the roles for Alice, Bob and Carl. You might consider, Developer Debbie (writes code, signs commits), Release Engineer Ralph (maybe the project owner, also probably sets version number), Operator Ozzie (uses signed artifact), Attacker Ali (attempts to compromise supply chain).

lukpueh commented 5 years ago

Thanks again, @ultrasaurus, your feedback is very much appreciated! I contextualized your suggestions and submitted a new ticket in a place, where it will get more attention. :)

--> https://github.com/in-toto/in-toto/issues/284

adityasaky commented 3 years ago

I believe this has now been mostly addressed in #48. There's a link to both the source of the layout-web-tool and our instance hosted at in-toto.engineering.nyu.edu. I've also added in-toto.io as a repository link. :)

https://github.com/in-toto/in-toto/issues/284 has also been closed. Is it time to close this one?

cc @SantiagoTorres

adityasaky commented 1 year ago

Closing issue as I think it's been resolved here and in the reference implementation.