rewrite update page fix for #211, #210

[jonvnadelberg]

Summary

Need to clarify the overview page to make it simpler and more complete than it was previously.

Release Note

NONE

Documentation

Fix for #210 #211 doc only

[netlify]

✅ Deploy Preview for docssigstore ready!

Name	Link
🔨 Latest commit	44e4229
🔍 Latest deploy log	https://app.netlify.com/sites/docssigstore/deploys/64ececb353be210007d56591
😎 Deploy Preview	https://deploy-preview-235--docssigstore.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[jonvnadelberg]

I rewrote the overview page. Please review @olivekl, @smythp. Does this correct issues with overview or does it need more work?

[olivekl]

These are GREAT changes. Thank you!!

[smythp]

Thanks for this, I think this does flesh things out and give a more complete intro.

I still think we could be higher-level in the very first paragraph (or two paragraphs). Something along these lines:

Sigstore is an open-source project for improving software supply chain security. The initiative provides a framework for signing and verifying software artifacts and for recording software supply chain metadata to an immutable ledger. Sigstore also maintains a suite of clients, APIs, and roots of trust, enabling developers to demonstrate and verify the provenance of software artifacts.

I guess when I look at a FOSS project, I want to know what kind of artifact it is (i.e., framework, client-side software, server-side software, specification, prototype, etc.) before reading about benefits and background, as it's essential context. I know we do a bunch of things here and it's consortial, which makes things more complicated, but functionally it's a FOSS project that provides roots of trust (like certs), a framework for signing and verifying stuff (artifacts is a good word as this is broad), and maintaining specific clients (like Cosign) and APIs (like the Rekor API).

One more suggestion (feel free to ignore) is that I do think it's helpful to have the quickstart links be pretty high up in the page, as they're really useful for a dev in a hurry. (That is, all devs.)

[olivekl]

Thanks for this, I think this does flesh things out and give a more complete intro.

I still think we could be higher-level in the very first paragraph (or two paragraphs). Something along these lines:

Sigstore is an open-source project for improving software supply chain security. The initiative provides a framework for signing and verifying software artifacts and for recording software supply chain metadata to an immutable ledger. Sigstore also maintains a suite of clients, APIs, and roots of trust, enabling developers to demonstrate and verify the provenance of software artifacts.

I agree in part: "Sigstore empowers developers..." (the current version) doesn't say what Sigstore is, so it'd be good to answer that more clearly in the opening sentence. I think the current version is clearer about what it actually does, though, in terms of what you can sign and how it's differs (no need to manage keys). "Immutable ledger" and "verify the provenance" are terms that are too technical to have in the opening paragraph, in my opinion.

Would you be open to a mashup?
Sigstore is an open source project for improving software supply chain security. The Sigstore framework and tooling empowers software developers and consumers to securely sign and verify software artifacts such as release files, container images, binaries, software bills of materials (SBOMs), and more. The signing materials are stored in a tamper-resistant public log so there’s no need to manage or store keys.

(Side note: we're not hyphenating open source even when used as a compound adjective (nor supply chain). It reduces confusion about when to use it vs not and doesn't lose an precision since both phrases are easily understood without the hyphen. The open source community seems to be moving in this direction grammatically.)

[smythp]

That sounds good to me. My only real concern is getting in there that it's a project that offers a framework and maintains specific things, and mentioning what those things are, and that seems to do it. Agreed that we do cover what we do well, it's just not initially clear whether Sigstore is a protocol, server-side software, framework, etc., and we should cover that early on.

Think the adjectival open source versus open-source makes sense. I remember having these discussions with neologisms like ebook versus e-book back in the day, and the simpler version typically does and should win out.

Thank you, I know it's kind of annoying to write these intros by committee.