DISCUSSION: Move docs to GitHub Pages?

[olivekl]

Scorecard's docs are a treasure trove of information, but the length of the ReadMe is getting unwieldy. Would there be interest in standing up a GitHub Pages site to improve the navigation experience?

Here's an example of the layout from OSV-Scanner.

[spencerschrock]

I think the OSV-scanner docs look pretty snazzy.

I'm curious how this would work with our checks.yaml generation, and the probes code. One benefit of the README is a permalink, we might lose some of that if we do a github pages experience.

[hayleycd]

I looked into the checks.yaml generation and I think you could probably still do that.

I believe it could be possible to include the relevant markdown here to make it a "GitHub page" (it would look something like these lines). It would generate the same, but include the necessary text to be rendered as a GitHub page.

But that is just a guess. And I am not sure what the probes code is, so I don't have an opinion on that one.

[hayleycd]

Hi @ariathaker! @olivekl mentioned you were interested in helping convert the scorecard docs to a GitHub page. I have been through this process a few times for some related projects and would be happy to help you in any way. This particular project might require a little more work and debugging based on the issues discussed above and I am happy to help you do that, answer any GitHub pages questions you may have, or even work on it together from a shared branch on one of our forks.

[ariathaker]

Hi all, @hayleycd and I have put up a proof of concept for the potential migration to Github Pages. It's here: https://ariathaker.github.io/boom/

We haven't figured out the auto-updating pages yet, but wanted to share the proof of concept for initial feedback from the maintainer team before we work on figuring out those details. What do you think @spencerschrock?

[spencerschrock]

We haven't figured out the auto-updating pages yet,

This would probably be a mix of GitHub Actions:

1. one to publish the new GitHub Pages (or Netlify)
2. one to make sure PRs which update the various yaml files also regenerate the Markdown files or they cant be merged.

initial feedback from the maintainer team

we have a website already at https://securityscorecards.dev/ with some doc info using Netlify, and long term I'd want there to just be one website, instead of having that and a GitHub Pages site. I know we can point our domain (or portions of it) at GitHub pages for example, but is not something that needs to be done from the beginning.

Tagging other @ossf/scorecard-maintainers for thoughts

[hayleycd]

Thanks for setting this up @ariathaker!

A couple of thoughts/things for the team to consider:

1. GitHub pages supports using custom domains. So we don't need to use the typical github-user.github.io/repository-name url if we don't want to.

2. We would need to tweak the code that generates the checks documentation. I think it would just be a matter of including the necessary header for Jekyll to recognize the page but this change will require dev support.

3. We should remember that changes in the docs have taken place since work on the proof of concept (POC) began. The POC is useful for understanding what the docs could look like/whether we want to invest more time, but if we decide to implement it, we should update it with the docs currently in the main repository not from the POC.

4. GitHub pages either build from the /docs folder or from root. This POC builds from root. We would want the real scorecard docs to build from /docs. There is a current /docs folder. So we may need to adjust our file structure slightly to make sure that things can be built correctly and the doc generation files don't break.

And smaller nits/feedback/opinions:

1. There are two copies of 'Scalable Scorecard"
2. I am not sure I like how the checks documentation is organized (with the table being on the parent page and the breakdown being on the child page). I think these two pages should be on the same level (both children of a shared parent page, both on the top level, or have the pages combined)