Skip to content

Conversation

@sei-renae
Copy link
Contributor

The target audience for the Explanation is a non-expert, and per diataxis.fr, should be able to casually read this and get an overview of what is SSVC.

This PR:
Adds the Explanation document
Modifies the main index page cards to Add the Explanation and Delete Learning SSVC
Modifies the menu bar via mkdocs.yml per index page cards
Moves Learning SSVC to Reference

image image

Copy link
Contributor

@ahouseholder ahouseholder left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few general thoughts:

  • I'm concerned about length for an intro doc
  • It might be better to give readers the intro, then let them do a choose-your-own-adventure based on what roles they have. I'm thinking something like:
flowchart TB

intro --> stakeholders
stakeholders --> supplier
stakeholders --> deployer
stakeholders --> coordinator
supplier --> sddp[supplier decisions and decision points]
deployer --> dddp[deployer decisions and decision points]
coordinator --> cddp[coordinator decisions and decision points]
sddp --> fn[final notes]
dddp --> fn
cddp --> fn
Loading

This could be done as a series of pages (one for each stakeholder role) that includes
links to each of the other paths.

If you want to keep it in one page, we could do it using content tabs That might get weird with longer content though.

Copy link
Contributor

@sei-bkoo sei-bkoo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are some thoughts:

  • I would consider removing the code blocks that appear after each decision point definition. A first time reader might be confused for what these are for (especially those who might stumble upon this on the internet). Apologies if they don't appear or if there is a good reason for those to be there.
  • Something to consider down the line (which I actually want to work on) is some kind of example (text or visual) to keep enhancing accessibility. See examples here and here. Whether it should be on the same page as this somehow or as another page, we can discuss later!

@sei-renae
Copy link
Contributor Author

Also at sei-renae#1

@sei-renae sei-renae marked this pull request as ready for review June 4, 2025 13:14
Copy link
Contributor

@ahouseholder ahouseholder left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Link Checker is failing on a few links (see checks below)
  2. One last change request: could you please rename explanation.md to either
  • ssvc_overview.md (matches the nav menu name)
  • what_is_ssvc.md (matches the h1 in the page itself)

I'm leaning toward ssvc_overview.md since the nav is less likely to change in the future than the page title.

This is entirely an "ease of future maintenance" request, so you don't have to consult the mkdocs.yml or the home page to figure out which file contains the SSVC overview doc. explanation.md is too generic to be obvious.

@ahouseholder
Copy link
Contributor

Still need to fix these:

URL        `topics/decision_trees/'
Name       `Decision Trees'
Parent URL file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/index.html, line 3943, col 314
Real URL   file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/topics/decision_trees/
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/runner/work/SSVC/SSVC/site/ssvc_overview/topics/decision_trees/'>

URL        `howto/coordination_triage_decision/#coordinator-triage-units-of-work'
Name       `CERT/CC Coordinated Vulnerability Disclosure (CVD) project'
Parent URL file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/index.html, line 3954, col 48
Real URL   file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/howto/coordination_triage_decision/
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/runner/work/SSVC/SSVC/site/ssvc_overview/howto/coordination_triage_decision/'>
10 threads active,    [37](https://github.com/CERTCC/SSVC/actions/runs/15495231228/job/43630238573?pr=716#step:7:38) links queued,  795 links in 842 URLs checked, runtime 11 seconds

URL        `reference/index'
Name       `Reference material'
Parent URL file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/index.html, line 4220, col 4
Real URL   file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/reference/index
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/runner/work/SSVC/SSVC/site/ssvc_overview/reference/index'>

URL        `howto/tree_customization'
Name       `Guidance for customizing a Decision Tree'
Parent URL file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/index.html, line [42](https://github.com/CERTCC/SSVC/actions/runs/15495231228/job/43630238573?pr=716#step:7:43)21, col 4
Real URL   file:///home/runner/work/SSVC/SSVC/site/ssvc_overview/howto/tree_customization
Check time 0.000 seconds
Result     Error: URLError: <urlopen error [Errno 2] No such file or directory: '/home/runner/work/SSVC/SSVC/site/ssvc_overview/howto/tree_customization'>

@ahouseholder ahouseholder merged commit 933ae74 into CERTCC:main Jun 6, 2025
2 checks passed
@ahouseholder ahouseholder added this to the 2025-09 milestone Aug 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants