sigstore
Fleshing out Docs
Docs Improvement
TL;DR - I would like to get involved Sigstore and help improve documentation with a focus on the installation and configuration of each component.
Intro
Hi all, I primarily work in airg-gap or heavily internet restricted environments and have recently finished a few sigstore implementations (I also maintain them).
The very high level of my experience is highly available configurations of:
- Trillian with Galera
- Rekor
- Fulcio
- TUF server
- CTLog
Some other notes:
- Hashicorp Vault is used for the certificate issuer for all components. (Optional)
- The system is integrated with Keycloak and supports interactive and non-interactive (via a custom CLI) Keyless signing.
- Cosign and Gitsign are mandatory within the environments.
Issues
I found the documentation was primarily focused on:
- How to make use of Sigstore's various components as a client
- What's actually going on under the hood, i.e
Fulcio Certificate Issuing
It also took a bit of reading to understand what was going on between the components, the resources below were great and provided a lot of the information, in most of my integration experience I would expect this information to be available as centralized docs though:
- https://github.com/sigstore/scaffolding
- https://github.com/tstromberg/sigstore-the-local-way
- https://github.com/stacklok/sigstore-the-hard-way
- Reviewing the source for Fulcio/Rekor/Cosign etc
The areas I would like to improve:
- Create documentation sections for reliant, third party components (or add under relying components) such as CTLog/Trillian
- Documentation of component configuration options, i.e Fulcio, Rekor, CTLog, Trillian & Policy Controller
- Troubleshooting documentation/FAQ's for component interaction, i.e Fulcio -> CTLog
If this work would be welcome I would love the oppurtunity to contribute!
Regards,
Andrew
I was going to open a separate issue, but you've touched on several related points, so thank you for getting the conversation started! If you don't mind, I'll add some of my own suggestions to keep the discussions of these closely related issues together.
Like @iron-rain, I'd like to open a discussion of potential long-term efforts to update Sigstore documentation.
We can address the open questions here or move to a doc for easier collaboration on potential outlines. Ideally, let's organize our plans as a project within the GitHub UI so we can assign tasks and keep track over the next several months.
The biggest pain points in my opinion fall into three areas: unclear user journeys out-of-date and disorganized information, and technical/platform issues.
User Journeys
The paths for the main user journeys are improving thanks to recent PRs! We can continue work in this area to make the documentation even more user friendly.
-
I propose the following critical user journeys (CUJs) to describe what most users want to do with Sigstore, to guide documentation decisions:
- (High priority) As a developer, I want to sign an artifact so that users can trust it is what it's supposed to be. (Using both ephemeral keys and my own keys.)
- (High priority) As someone who just downloaded an artifact, I want to verify its signature so that I can trust that I got the right artifact.
- (Medium priority) As a newcomer to open source security topics, I want to learn more about signing, package integrity problems, and how Sigstore helps so that I can understand the current landscape of problems and solutions
- (Medium priority) As a developer interested in contributing to or building on Sigstore, I want to find technical information about how the tools work so I can improve or expand the project.
- (Medium-Low priority) As a release architect (enterprise scale), I want to find information about setting up a secure process so I can establish one for my organization.
-
Create some lightweight friction logs for the main user journeys we settle on. @psmyth has volunteered to start on some of these; ideally we can get several volunteers to work through these. I’ve shared a basic friction log template with @psmyth that we can potentially use to get feedback in a consistent format.
-
Based on the friction logs and agreed-upon user journeys, let's discuss reordering the left-hand navigation based on what the user wants to do, not the tool name.
- For example, rather than headings for Cosign, Fulcio, Rekor, heading could be Signing, Verifying, Developing with Sigstore, etc (@jonvnadelberg has expressed interest in creating and sharing a reworked structural outline for discussion)
Content audits
Currently there's information and documentation spread between: sigstore.dev, docs.sigstore.dev, Cosign, Fulcio, and Rekor repositories, and possibly elsewhere. Because of this, it's hard to tell what's covered vs. what's not; additionally, some content is out-of-date, some is potentially superfluous, and it's not clear to users which parts are useful and which might be misleading.
-
One or more people could undertake a thorough audit to:
- Find all info (including any stray docs in project repos)
- Identify what is incorrect or out of date
- Separate out user docs from developer docs (which are currently intermingled)
- Prune anything unnecessary so the useful content is more easily surfaced
-
It'd be good to add a contributor ladder and guide, including information on how to update docs (what goes where, given the potential for confusion across two sites and multiple project repos. @dicodes, do you have information about an OpenSSF contributor ladder potentially in the works?
Technical issues
- Caching issues are showing old versions of the site to users. There's some discussion of replatforming the site, which @smythp has expressed interest in taking on.
Questions for discussion:
- Where should we keep developer docs so they are separate from user docs? Should documentation about contributing to Sigstore be housed on docs.sigstore.dev (in a clearly separate section from user docs), or in the individual repos (i.e., rekor, fulcio, etc.)?
- Is there support for restructuring the left-hand nav bar to be goal-focused rather than tool-focused?
- Any other thoughts or suggestions?
@haydentherapper @ltagliaferri
PS: Let me know if you'd like me to delete this comment and open a separate issue!
Huge +1 to everything you've written @olivekl, this looks like a great plan. Focusing on the user journeys will greatly improve the documentation.
Where should we keep developer docs so they are separate from user docs? Should documentation about contributing to Sigstore be housed on docs.sigstore.dev (in a clearly separate section from user docs), or in the individual repos (i.e., rekor, fulcio, etc.)?
Developer documentation quickly gets out of date if it's hosted in a different repository, as devs won't remember to update the docs. I would prefer the documentation remain in the individual repos. However I'd like the documentation to be discoverable on docs.sigstore.dev too. Ideally the dev docs would also go through a similar review for readability/clarity as with user-focused documentation.
One option could be to have dev documentation written in the respective repos and then a sync script copies over changes into docs.sigstore.dev, where it can undergo more review before merging.
Is there support for restructuring the left-hand nav bar to be goal-focused rather than tool-focused?
Yes :)
