"How To" on using github to help with SSVC

[ahouseholder]

It came up in conversation that folks might be hesitant to contribute because Github use can be intimidating. So the goal here is to make it easier for folks to contribute.

Some initial thoughts on approach to resolution:

• We probably shouldn't be writing how-to-use-github docs. We should find them and point to them.
• We need to decide whether any such how-to pointers are
  1. included as part of the SSVC documentation website (i.e., in /docs), or
  2. included in the accompanying Github Wiki https://github.com/CERTCC/SSVC/wiki

I think they belong in the wiki, with maybe a pointer from https://certcc.github.io/SSVC-staging/about/contributing/ to that.

Starting on a list of extant resources:

• Contributing to a Project https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project
• Editing Files https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
• Creating an Issue https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue
• Creating a Pull Request https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
• Linking a Pull Request to an Issue https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue

I'm not sure what other content we might want to include. Comments welcome.

[cgyarbrough]

I agree that GitHub specific 'how to' topics should be directed to the GitHub site. SSVC specific topics would be more effectively handled in the SSVC Wiki page.

[j---]

One question is whether there are how-to's that are targeted at folks who are not SW developers. GitHub how-to's tend to assume a baseline amount of knowledge of a SW developer. Since we are working with a fair amount of plain text, and want to solicit feedback from folks who may not be SW devs, are we aware of any existing videos or resources that are a sort of how to orient into the github docs, maybe with a focus on the github web GUI?
A full function web editor is in beta, as of this writing https://docs.github.com/en/codespaces/the-githubdev-web-based-editor
This video is fine, but still more focused on SW devs than I was thinking: https://www.youtube.com/watch?v=tRZGeaHPoaw

Also not clear whether github desktop would be useful for folks https://docs.github.com/en/desktop/overview/about-github-desktop ?

Obviously we should not try to solve the whole "non-developers using github" training problem. But maybe we can try to find resources we could point folks towards. My cursory 20 minute search did not turn up anything that was obviously a good option, though.

[cgyarbrough]

I agree that the videos and GItHub documentation assumes that the user will have some SW programming familiarity. My question is what level of proficiency should we assume in documenting how to use and contribute to the SSVC GitHub project? Levels of familiarity with the concepts behind how to write and version SW should be accounted for but how much of that is any one given project's responsibility? Also, do we want folks who aren't familiar with how coding works (as evidenced in the videos and help files) actively contributing. We do want the ideas they bring for sure but shouldn't the burden be on the contributor to learn?

[j---]

Can we add a "suggestion box" link to the front of the website that is just a link to the "create a new issue" link? https://github.com/CERTCC/SSVC/issues/new/choose
Possibly new discussion would be better. Not sure.

[ahouseholder]

Can we add a "suggestion box" link to the front of the website that is just a link to the "create a new issue" link? https://github.com/CERTCC/SSVC/issues/new/choose Possibly new discussion would be better. Not sure.

This comment is now the subject of:

• Make it more obvious how to contribute for someone looking at web docs #461
• Add community engagement links #468

[j---]

With #468 done, would it be enough to add a list of links to help resources about GitHub (the links in the first comment here) and provide a pointer to that list of links? Assuming the links go on the wiki, we may want to point people from the website to there from the links. Does that pointer just get added to the bottom of the box of contributing options created for #468?

[ahouseholder]

I just created https://github.com/CERTCC/SSVC/wiki/Github-Tips-for-SSVC-contributors
with a few more words & links. I'll add a link to that page to the include text and create a PR.