Migrate documentation to docs.sigstore.dev

[lukehinds]

We now have a nice docs site, so let's start moving content into there.

Seeking volunteers to help with this and also add more content.

[endorama]

Happy to help with this! Which content should be migrated? Everything from the doc/ folder?

[lukehinds]

Thanks @endorama , /doc is just auto generated stuff , most of its in the .md files in the root (including the main README.md)

[dlorenc]

+1, we should figure out a migration plan and cutoff to get everything into the other site.

[endorama]

I was going through the docs for the website, do I need an invite to Netlify CMS?

At the moment I would start migrating pages and writing a script to synchronize them between cosign and website repositories. This would allow to have the content on the website quickly with an easy path for manual updates.

What is the expected flow once the migration is finished? Will cosign docs still be in this repo or every contribution must/will happen in website repo?

[lukehinds]

Already made a start on this (in fact it should be good to go)

sigstore/sigstore-website#67

[dlorenc]

Nice!

Now we have to figure out how to best link over to those docs from here, and what should stay here.

Maybe this readme can contain installation instructions, a quickstart, and then a link to the full docs on the website?

[dlorenc]

One other quick thing I noticed when browsing those docs: we should probably leave the specification files here in this repo:

https://docs.sigstore.dev/cosign/cosign_predicate_spec
https://docs.sigstore.dev/cosign/specifications

[endorama]

we should probably leave the specification files here in this repo

@dlorenc do you think is better to just link to the main branch version of those files from the docs website or duplicate the content?

[dlorenc]

@dlorenc do you think is better to just link to the main branch version of those files from the docs website or duplicate the content?

Yeah - linking to here would be best I think.

[ChrisJBurns]

Just going through all the GFI's and found this one is the oldest, thought I'd offer my help to get it across the line :) - providing there's anything left to do @dlorenc @endorama @lukehinds ?

[haydentherapper]

We should increase the number of examples in docs.sigstore.dev, we have lots of examples for container signing but not many for blob signing. https://github.com/sigstore/cosign/blob/main/KMS.md should be brought over to the docs.

Lots of documentation will need to be updated as part of #2534 also.

https://github.com/sigstore/cosign/tree/main/specs should be cleaned up and added.

[znewman01]

Thanks so much @ChrisJBurns !

+1 to migrating lots of KMS.md along with README.md, EXAMPLES.md, KEYLESS.md, and IMPORT.md. We can leave a few simple README.md examples in, with a pointer back to docs.sigstore.dev.

Lots of documentation will need to be updated as part of #2534 also.

Agreed but I think because that's tracked separately it doesn't need to be addressed as part of this issue.

https://github.com/sigstore/cosign/tree/main/specs should be cleaned up and added.

IMO we should leave that in this repo. (We deliberately pulled it out in sigstore/sigstore-website#74)

[ChrisJBurns]

Thanks @znewman01 although not sure if I'm looking in the right place?

The file paths in the sigstore-website repo that is being used in @lukehinds PR above is content/en/cosign? But that path doesn't exist anymore?

Am I correct in assuming that we use content/docs/... ? If so, there doesn't really seem to be anything in there either. Additionally, I've clicked a couple of Edit this page links on the Docs site and they take me to the .md file on the docs branch in this (cosign) repo (but the file doesn't exist anymore).

There's also a couple of things that I'm getting mixed up by, mainly that (I believe) this PR is to port the docs from this repo into the sigstore-website one. However in the sigstore-website repo, there is a README.md sentence saying (2 months ago) that the cosign repo is where the docs live. 😄 .

So am a bit confused atm, are we porting over the docs from this repo into the sigstore-website repo, or are we just refactoring the docs that live in this repo, into the docs folder of this repo?

[ltagliaferri]

The documentation repo is now https://github.com/sigstore/docs (sigstore/sigstore-website is the frontend "Marketing" site for Sigstore)

The Cosign documentation is in content/en/cosign (https://github.com/sigstore/docs/tree/main/content/en/cosign)

I'm happy to collaborate on bringing more things over. There are a few known URL issues on the docs site, and I have a PR open to address those

[ChrisJBurns]

Thank you @ltagliaferri I'm going to start with the README.md, EXAMPLES.md, KEYLESS.md, and IMPORT.md docs.

[znewman01]

TYVM @ChrisJBurns !

I'll warn you right now: you may have to be a little patient because we may say "oh leave that in README.md" a bunch 😄

If you start with adding things to the docs before we copy them from Cosign (feel free to CC me in, I don't usually get docs repo notifications) that'll probably be safer.

[ChrisJBurns]

@znewman01 Shall do 👍 What I can do is put a NOTE: in the relevant parts of the README.md, EXAMPLES.md etc just to say a particular part has been migrated? Therefore, when folks are comfortable they can easily see what needs to be removed in future? Either that, or I can just raise an issue to remove the parts that have been successfully migrated? I'm easy either way :)

[znewman01]

Just a note should be fine!

Will review your PR shortly, I'm unburying myself from a week's holiday right now :)

[ChrisJBurns]

sigstore/docs#123 will see to the last non README.md docs page that lives in the cosign repo root directory that we've spoke about on this issue.
Do we know what parts of the README.md we'd want to migrate over? Or is that a deeper discussion and something to possibly delay?

Also would we know what would be required to close this ticket? Are there a list of docs pages we want to migrate over, or have we done the majority of them? I ask because there are also the following:

• https://github.com/sigstore/cosign/blob/main/KMS.md
• https://github.com/sigstore/cosign/blob/main/PKCS11.md
• https://github.com/sigstore/cosign/blob/main/TOKENS.md
• https://github.com/sigstore/cosign/blob/main/USAGE.md

Would we want to migrate those also?

[haydentherapper]

I would prefer we don't migrate anything in the README over. At a glance, everything appears to be covered in documentation or is outdated.

Out of what's listed, USAGE is likely redundant, so I don't think it needs to be moved. The other three might fit somewhere, but it'd be good to confirm if they are redundant.

[ChrisJBurns]

@haydentherapper Yep agreed on the USAGE.md point, I see a lot of duplicated information in there that we've already got on the docs sites, although worth confirming.

[ChrisJBurns]

@lukehinds @znewman01 @haydentherapper @dlorenc @ltagliaferri @endorama

So I think we should be able to consider closing this ticket as of now.

The following docs have been migrated from cosign into the relevant docs pages and are all available on the https://docs.sigstore.dev/.

• cosign/KMS.md - docs/kms - Docs Site Page
• cosign/examples.md - was merged into docs/sign - Docs Site Page
• cosign/keyless.md - docs/keyless - Docs Site Page
• cosign/import.md - docs/import - Docs Site Page
• cosign/tokens.md - docs/hardware-based-tokens - Docs Site Page
• cosign/usage.md - Content already existed in docs/sign & docs/verify
• cosign/pkcs11.md - docs/pkcs11 - Docs Site Page

A deprecation note has been added to all of the above mentioned cosign doc pages and can be removed whenever you're ready. This should stop folks from adding more content to the pages and instead will redirect them to the official docs repository.

I haven't touched the cosign/README.md just because it seems we have to agree what bits to take out and what bits to leave in there. My recommendation as a first instance though is to probably remove the instances of "I" and replace with "We"?

Example:

"I believe this tool is complementary to TUF, and they can be used together. I haven't tried yet, but think we can also reuse a registry for TUF storage."

Would become:

"We believe this tool is complementary to TUF, and they can be used together. We haven't tried yet, but we think we can also reuse a registry for TUF storage."

There's only a couple of instances of this, so I'm nitpicking at this point 😄

I'm more than happy to do the README.md changes, as long as we can agree what changes we want to make with regards to the content it needs to have and content we can take out (as some of it is most likely covered on the docs site now).

[znewman]

@ChrisJBurns Why am I tagged in this?

[znewman01]

@znewman I think he meant me :)

[ChrisJBurns]

@znewman Apologies, I meant @znewman01, I got a bit trigger happy with the send button 😢

[znewman01]

Happy to close it out for now! Thanks for the hard work here @ChrisJBurns