-
Notifications
You must be signed in to change notification settings - Fork 42
Add an 'Explanation' Overview document #716
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
…e Tutorial to Reference
ahouseholder
left a comment
There was a problem hiding this 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
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.
sei-bkoo
left a comment
There was a problem hiding this 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!
|
Also at sei-renae#1 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Link Checker is failing on a few links (see checks below)
- One last change request: could you please rename
explanation.mdto 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.
|
Still need to fix these: |
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