New documentation content

[olivekl]

Following the docs restructuring and replatforming (amazing work, @smythp and @jonvnadelberg!), a next stage of improvements could include new content:

• Terminology page
  • A single page that defines specialized terms (i.e, "witnessing" in the context of transparency)
• New user journey
  • Docs that support users who want to automate Sigstore processes; user journey = “I want to build Sigstore into my tooling or workflow)
    DONE - Explanation of docs structure - A brief guide about where to house new documentation depending on topic (i.e., tooling repos, docs website, project website) so things stay tidy long term

Opening this issue for discussion, prioritization, and (hopefully) assignments!

@haydentherapper @ltagliaferri @smythp @jonvnadelberg

[smythp]

Unless someone else would prefer to take it on, I can take an initial pass at a terminology page.

[olivekl]

Unless someone else would prefer to take it on, I can take an initial pass at a terminology page.

Sounds good to me! Btw, it occurred to me that one of the OpenSSF working groups created a glossary of terms related to supply chain security. Probably no need to recreate the wheel for the terms they've covered; Sigstore's could either focus solely on transparency terms, draw from the OpenSSF's version, or link out to the OpenSSF's with a note to look there for more general terms?
Edit: scratch that, I just dug deeper and there are no definitions included yet. Whoops.

[ltagliaferri]

Chainguard Academy also put together a glossary: https://edu.chainguard.dev/software-security/glossary/ (it's CC BY NC so you can grab some terms if you would like).

[olivekl]

Following up here!

@smythp has started work on the terminology page and accessibility review, and @jonvnadelberg has finished the documentation location guide (which has been merged).

As for next steps, @jonvnadelberg is interested in creating some self-evident structure for the tooling repos to house developer docs. He is also interested in laying out out the bones for the additional user journey we discussed, about creating Sigstore integrations.

Some questions:

• Who is the correct SME to connect with re: documentation needs for the Sigstore integration user journey?
• What sort of developer docs will be most useful in the tooling repos? Who are some of the contributors we could connect with here?

@ltagliaferri @haydentherapper

[haydentherapper]

Did we decide on if we wanted developer documentation to live in the docs repo, or live in individual project repos and get synced back?

[smythp]

My recollection is that we were going to keep the project docs in their own repos, but link out to them here. Coming up with ways to mirror them has a lot of maintenance overhead.

Probably we should link to each project under a specific heading on the left sidebar. I just created #250 for it, if anyone would like to advocate for a different approach, let's follow up there.

[olivekl]

Agreed, I think it's best to keep the developer docs in the repos and then just link to them, rather than set up a pipeline to pull them in from the repos to the website docs.