Skip to content

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

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

revise topics/decision trees for decision tables terminology shift#1111
sei-renae wants to merge 9 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.

@sei-renae
Copy link
Copy Markdown
Contributor Author

image Resolves #991

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@ahouseholder ahouseholder requested a review from Copilot April 13, 2026 16:56
@ahouseholder ahouseholder added the content/semantic Changes to the semantic content of the SSVC documentation label Apr 13, 2026
@ahouseholder ahouseholder added this to the 2026-06 milestone Apr 13, 2026
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

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

@@ -0,0 +1,11 @@
!!! note inline end "About the term "decision tree""
Comment on lines +61 to +65
and codified it in
[src/SSVC_csv-to-latex.py](https://github.com/CERTCC/SSVC/tree/main/src). Why
have we gone to this trouble when (for example) the R data.tree package has a
handy print-to-ASCII function? Because this function produces output like the
following:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content/semantic Changes to the semantic content of the SSVC documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Revise topics/decision_trees for Decision Tables

3 participants