revise topics/decision trees for decision tables terminology shift#1111
revise topics/decision trees for decision tables terminology shift#1111
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the “Decision Trees” topic documentation to clarify SSVC’s use of “decision tree” (operations-research meaning) vs. the machine-learning meaning, and to note the SSVC v2025.9 terminology shift toward “decision table” to reduce confusion.
Changes:
- Adds an inline note explaining SSVC’s terminology and linking to the relevant ADR.
- Refreshes/clarifies external references (e.g., VRDA,
data.tree) and reflows text for readability. - Minor documentation formatting updates in the examples and surrounding prose.
docs/topics/decision_trees.md
Outdated
|
|
||
| A decision tree is an acyclic structure where nodes represent aspects of the decision or relevant properties and branches represent possible options for each aspect or property. | ||
| Each decision point can have two or more options. | ||
| !!! note inline end "About the term "decision tree"" |
There was a problem hiding this comment.
The admonition title uses nested double quotes ("About the term "decision tree""), which will likely break MkDocs/Material admonition parsing. Use a title without nested quotes (e.g., single quotes around decision tree) or escape the inner quotes so the admonition renders correctly.
| !!! note inline end "About the term "decision tree"" | |
| !!! note inline end "About the term 'decision tree'" |
docs/topics/decision_trees.md
Outdated
| This paper continues roughly in the vein of such work to construct multiple decision trees for prioritization within the vulnerability management process. | ||
| Starting in SSVC v2025.9, we shifted to the term decision table to avoid | ||
| confusion with the ML meaning. For more information, see | ||
| [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). |
There was a problem hiding this comment.
The ADR link target appears to be incorrect. In this repo the ADR filename is docs/adr/0014-use-decision-table-terminology.md, and from docs/topics/decision_trees.md the relative path should likely be ../adr/... (not ../../docs/adr/...). As written, this link will 404 in the rendered docs.
| [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). | |
| [ADR-0014](../adr/0014-use-decision-table-terminology.md). |
| represented as a decision tree. The full tree can be found | ||
| [here](cvss_full_tree.md). This tree representation is functional, but not as | ||
| flexible or aesthetic as might be hoped. The visualizations provided by R are | ||
| geared towards analysis of decision trees in a random forest ML model, rather | ||
| than operations-research type trees. |
There was a problem hiding this comment.
Link text "here" is non-descriptive and violates the repo's markdownlint rule for descriptive link text (MD059). Replace with something descriptive like “the full CVSS v3 tree” so the link remains meaningful out of context.
| represented as a decision tree. The full tree can be found | |
| [here](cvss_full_tree.md). This tree representation is functional, but not as | |
| flexible or aesthetic as might be hoped. The visualizations provided by R are | |
| geared towards analysis of decision trees in a random forest ML model, rather | |
| than operations-research type trees. | |
| represented as a decision tree. [The full CVSS version 3.0 decision tree] | |
| (cvss_full_tree.md) shows the complete structure. This tree representation is | |
| functional, but not as flexible or aesthetic as might be hoped. The | |
| visualizations provided by R are geared towards analysis of decision trees in a | |
| random forest ML model, rather than operations-research type trees. |
Resolves #991
|
remove stray space Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

This pull request updates the documentation for decision trees to clarify terminology and improve explanations, especially distinguishing between machine learning and operations-research meanings. It also enhances formatting and improves a reference link in the document.
Terminology clarification and context:
Documentation and formatting improvements:
data.treepackage, to use direct links and clearer descriptions.Markdownlint is unhappy about a few things:
Resolves #990