Re-arrange sigstore docs so that they are more clear to readers

[hayleycd]

Addresses issue #191

Summary

Reorganize documentation. Please see any comments by @jonvnadelberg.

I opened this pull request to solve a git issue, but he did the work. (This replaces #209 which had the git issues)

Release Note

None

Documentation

This is a documentation change.

[netlify]

✅ Deploy Preview for docssigstore ready!

Name	Link
🔨 Latest commit	beb2b34
🔍 Latest deploy log	https://app.netlify.com/sites/docssigstore/deploys/64d65ca4a77a67000802dd39
😎 Deploy Preview	https://deploy-preview-210--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.

[olivekl]

Thank you, @hayleycd , for getting this PR to work, and @jonvnadelberg for all the work it reflects! @ltagliaferri @haydentherapper @smythp

[haydentherapper]

This file was previously about contributing to docs, not contributing to Sigstore in general. Can we move the newly added content to the top of this file, and have subsections for specific projects, docs being the only one for now (we can add ones for fulcio, cosign, rekor, etc later on)?

[haydentherapper]

@olivekl what do you think about how to organize this?

[olivekl]

So one Contributing page that has info on how to contribute to Sigstore in general, contribute to docs specifically, as well as small sections on each subproject (which I imagine would link out to each repo's docs on GitHub)? That makes sense to me. I think having everything together is a good idea, even if some of the sections link out for more info.

[jonvnadelberg]

OK, I'll edit the "Contributing" section and add various subsections to it.

[haydentherapper]

I think the System Configuration section should be higher up, because installation is the first step. I would recommend it's after "About Sigstore" and before "Signing"

[jonvnadelberg]

We were thinking that you'd only install and configure once, but I can move it.

[haydentherapper]

Another option could be a link in the first page of Signing that says "as a prereq, install cosign" and link to later documentation?

[jonvnadelberg]

Another option could be a link in the first page of Signing that says "as a prereq, install cosign" and link to later documentation?

The Getting Started page already says this:

Getting Started (Quick Start)
Cosign is a command line utility that can sign and verify software artifact, such as container images and blobs. Join us on our Slack channel. (Need an invite?)

Installation
To sign software artifacts and verify signatures using Sigstore, you need to install Cosign. Instructions to install Cosign can be found on the Cosign Installation page. This will allow you to sign and verify both blobs and containers.

Is that acceptable?

[haydentherapper]

Yea, that looks sufficient.

I'd recommend that Policy Controller and this section be moved above Certificate Authority and Transparency Log, given the latter two are for developers only.

[jonvnadelberg]

ok

[haydentherapper]

This should be under Certificate Authority, not Transparency Log

[jonvnadelberg]

OK, will move

[haydentherapper]

Change to "Fulcio", not Rekor

[jonvnadelberg]

OK

[haydentherapper]

Can we add this youtube link to a section on Get Help or learning more?

[jonvnadelberg]

OK

[haydentherapper]

Can we make sure the blog is linked somewhere? Maybe multiple places? Contributing, FAQ, Get Help, etc?

[jonvnadelberg]

I think we might want to just have it once, but I can put it in a few places if that's considered important.

[jonvnadelberg]

Thank you, @hayleycd , for getting this PR to work, and @jonvnadelberg for all the work it reflects! @ltagliaferri @haydentherapper @smythp

Thanks for the review, Hayden, I'm glad that nearly all of it is acceptable (I expected some change requests!). What we would like to do is install the changes as I have created them so far, and then quickly update with the requested changes. @ltagliaferri , can you go ahead and merge these changes in, and then we'll make the requested changes with additional PRs.

[smythp]

Hey @jonvnadelberg, @olivekl, @haydentherapper,

Thanks for this PR, it represents a tremendous effort. This kind of organization is a real challenge on a docs site with so many moving pieces, and I think this will make the project more approachable for those coming to it for the first time.

I'm going to give some feedback here, but agree it might be best to merge this and tackle issues afterward. Apologies for providing feedback so late in the process.

I really like the tooling page. It may make sense to link it early in the overview. We don't actually come right out and say what Sigstore is on that page (i.e., that it's a suite of tools), and we could add a line on that and link to Tooling.

In the sidebar, Certficate Issuing > Certificate Issuing

I think following this update there is a good opportunity to do more with the "How to Use Sigstore" links on the overview page. Right now, the initial quickstart goes to the Cosign page, and I think the more task-based approach piloted here would also work well there.

This has been discussed, but we may want to revisit where the threat model page fits in, as it takes a somewhat different tone from the other intro pages. Similarly , it feels like the former"help" topics, like "contributing," might be placed under another heading. (Just something to consider later.)

Really like the new section headings ("signing,," etc.) It seems that the "overview" pages under these headings might be a good place to socialize the names of the tools for those new to the project. For example, instead of the first page under "Signing" being named "Overview," it could be called "Cosign Overview." (The page is already titled Cosign, so it also makes semantic sense.) On the other hand, perhaps you have a larger vision involving a content overhaul, in which case this might not fit into that.

I'll make issues for these questions. I say full steam ahead. Thanks again for the major effort on this reorganization initiative!

[ltagliaferri]

I understand we want to merge in this change and then iterate on it. Since there was a typo in the sidebar I took a first pass on title casing all the titles there to be consistent (most were already title case)

I need another plus one to merge.

[olivekl]

Thank! Great changes!

[haydentherapper]

cc @bobcallaway for approval (there's no one else with push/merge permissions on the repo currently in the community repo)

[jonvnadelberg]

Hi @smythp I just created PR #235 does this cover what you would like to see?