Skip to content

revise topics/decision trees for decision tables terminology shift#1111

Open
sei-renae wants to merge 8 commits intomainfrom
990-revise-topics/decision_trees
Open

revise topics/decision trees for decision tables terminology shift#1111
sei-renae wants to merge 8 commits intomainfrom
990-revise-topics/decision_trees

Conversation

@sei-renae
Copy link
Copy Markdown
Contributor

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:

  • Added an inline note at the top explaining that SSVC uses "decision tree" in the operations-research sense (hand-crafted choices), not the machine learning sense (statistically learned models), and notes the terminology shift to "decision table" in SSVC v2025.9 to reduce confusion. Includes a link to ADR-0014 for further details.
image

Documentation and formatting improvements:

  • Applied markdownlint
  • Updated references to external resources, such as the VRDA framework and the R data.tree package, to use direct links and clearer descriptions.

Markdownlint is unhappy about a few things:

decision_trees.md:56 error MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
decision_trees.md:56 error MD046/code-block-style Code block style [Expected: indented; Actual: fenced]
decision_trees.md:77 error MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
decision_trees.md:77 error MD046/code-block-style Code block style [Expected: indented; Actual: fenced]
decision_trees.md:92:2 error MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]

Resolves #990

@sei-renae sei-renae requested a review from ahouseholder as a code owner April 3, 2026 19:50
Copilot AI review requested due to automatic review settings April 3, 2026 19:50
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

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.


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""
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
!!! note inline end "About the term "decision tree""
!!! note inline end "About the term 'decision tree'"

Copilot uses AI. Check for mistakes.
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).
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
[ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md).
[ADR-0014](../adr/0014-use-decision-table-terminology.md).

Copilot uses AI. Check for mistakes.
Comment on lines +91 to +95
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.
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
@sei-renae
Copy link
Copy Markdown
Contributor Author

image Resolves #991

Renae Metcalf and others added 4 commits April 3, 2026 16:04
remove stray space

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
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.

Revise topics/decision_trees for Decision Tables

2 participants