Add building block analogy explainer (#447)

* add links

* add to nav

* update enumerating_decisions.md

* update top-level topics overview to include bricks page

* adjust `discreteness` words to reflect interface with data/other bricks

docs/topics/decision_points_as_bricks.md

@@ -0,0 +1,107 @@
+# Putting the Pieces Together
+
+As we have continued to refine our concept of SSVC, we have an increasing understanding of the importance of
+[_Decision Points_](../reference/decision_points/index.md) as the foundational blocks from which the rest of the 
+SSVC concept is built. A second, but less foundational, concept are the [_Outcomes_](../reference/code/outcomes.md) that
+provide a vocabulary to describe the results of a decision.
+
+## Decision Points and Outcomes as Bricks
+
+Over time, we have come to think of decision points and outcomes as the LEGO® bricks of SSVC decision models.
+
+!!! info inline end "LEGO® Bricks"
+
+    LEGO® is a trademark of the [LEGO](https://www.lego.com/) Group of companies which does not sponsor, authorize or endorse this site.
+
+LEGO® Bricks come in different shapes and sizes, and they can be combined in different ways to build different structures.
+Similarly, decision points come in different shapes and sizes, and they can be combined in different ways to build 
+different decision models.
+And just as some bricks can be substituted for others to add variation, some decision points are substitutable for others. 
+
+We have realized that part of the value of enumerated decision points is that they provide a way to organize the information that is
+relevant to a decision. This organization is important because it helps us to understand the decision and to communicate
+the decision model to others. 
+
+Decision points and outcomes have a few key characteristics that make them useful for organizing information:
+
+- **Independence**: Each decision point represents a different aspect or dimension of the decision being modeled. This means that
+  the decision points are not redundant with each other. They may each be relevant to the decision, but they are relevant
+  in different ways.
+- **Discreteness**: Each decision point has a finite and discrete set of possible values. These specific values
+  that can then be mapped onto data collection and analysis results so that the data can be used to inform the decision.
+- **Well-Definedness**: Each decision point has a clear meaning and a clear, ordered set of possible values. This means that the decision
+  point values are not ambiguous or open to interpretation.
+
+In our brick analogy, the toy bricks are similarly independent, discrete, and well-defined. 
+Independence means that different bricks can serve different purposes in the model. 
+The pips on the bricks provide discrete points of attachment to allow bricks to connect together.
+Well-definedness (specification and manufacturing consistency) allows bricks to be combined effectively.
+
+## Model Kits and How to Use Them
+
+When you buy a model kit at the store, you get
+
+- a box with a picture of the model on the front, and sometimes variation suggestions on the back
+- a set of bricks, usually organized into bags appropriate for the different stages of the build
+- a set of instructions to tell you how to combine the bricks to build the model(s) pictured on the box
+
+From that starting point, there are a few different ways you might proceed:
+
+### Follow the examples as provided
+
+For many people, this is the experience they want.
+They want to build the model exactly as it is pictured on the box, and for that purpose they can follow the instructions provided.
+
+### Adapt the examples to suit your needs
+
+But other folks might want to build something else with the bricks.
+They might want to adapt the model slightly for their own purposes, perhaps turning an airplane with wheels into a seaplane by adding floats, or turning a car into a spaceship by adding a rocket booster.
+To do that, they might follow the instructions provided, just adapting them slightly with their own variations.
+Sometimes they might add a few extra bricks from their own collection to make the model more like what they want.
+
+### Combine different kits to build something new
+
+Perhaps they might want to combine two different model kits to build something new.
+Knowing which parts of the instructions to follow and which parts to ignore is a matter of understanding the properties
+of the bricks and the context of the model they want to build.
+
+### Build something completely original
+
+A builder might want to create something completely new that is not available in kit form, like a castle guarded by robots.
+In that scenario, they might think of the kit more as a supply of specific bricks than as a specific model.
+Advanced builders need to understand more about what they are trying to build and how the bricks can be combined to build it.
+
+The point is that the model kits serve as a starting point with a lot of flexibility, but it is up to the builder
+to decide how much of that flexibility to use. 
+
+## SSVC Decision Models as Kits
+
+Similarly, SSVC provides a set of "bricks" in the form of [decision points](../reference/decision_points/index.md)
+and [outcomes](../reference/code/outcomes.md). 
+We have provided a set of [example decision models](../howto/index.md) and [policies](../howto/index.md) to get you started.
+You might choose to simply use what we've provided as a starting point.
+Or you might already recognize that our example gets the structure of the decision model right, 
+but you need to adapt the outcomes or policy to better fit your situation.
+
+You might also recognize that you need to combine different example decision models to build the model you need.
+For example, you might recognize that you need to combine the [supplier decision model](../howto/supplier_tree.md)
+with the [deployer decision model](../howto/deployer_tree.md) to
+build a model that is relevant to your situation as both a supplier and a deployer.
+
+Or, perhaps you have a decision problem that we have not yet addressed with any of our examples.
+In that case, you might examine the [decision points](../reference/decision_points/index.md) we've provided and 
+decide which ones are relevant to your situation.
+You could choose to customize a decision point to better fit your situation, or you might choose to add a new decision point
+to better suit your needs.
+
+This is the embodiment of the _Stakeholder-Specific_ concept in [SSVC](../index.md): 
+SSVC provides the components for you to build your own decision models, and we provide some examples to get you started.
+If the examples are sufficient for your needs, then you can simply use them as they are.
+
+But we recognize that you are the expert in your own situation, and that you are in a better position than we are to 
+decide how to combine the provided components to build the decision model you need.
+If you need to adapt the components we've provided, or if you need to add new components, then we encourage you to do so.
+And if you think that your adaptations or additions would be useful to others, then we encourage you to share your
+[suggestions](https://github.com/CERTCC/SSVC/issues), [ideas](https://github.com/CERTCC/SSVC/discussions), and
+[changes](https://github.com/CERTCC/SSVC/pulls) with the [community](https://github.com/CERTCC/SSVC).
+

docs/topics/enumerating_decisions.md

@@ -1,7 +1,7 @@
 # Enumerating Decisions
 
 Stakeholders with different responsibilities in vulnerability management have very different decisions to make.
-{== This section ==} focuses on the differences among organizations based on their vulnerability management responsibilities.
+This section focuses on the differences among organizations based on their vulnerability management responsibilities.
 Some decision makers may have different responsibilities in relation to different software.
 
 !!! example "Example: Different Responsibilities for Different Software"
@@ -24,4 +24,4 @@ we recommend that the professionals making genuine decisions do three things:
 2. describe how they view their role(s)
 3. identify which software projects their decision relates to
 
-If their decisions are explicit, then the decision makers can use the recommendations from this document that are relevant to them.
+If their decisions are explicit, then the decision makers can use the recommendations from this documentation that are relevant to them.

docs/topics/index.md

@@ -85,6 +85,7 @@ The remainder of this section is organized as follows:
 - :material-state-machine: [**Current State of Practice**](state_of_practice.md)
 - :material-information-box-outline: [**Representing Information for Decisions About Vulnerabilities**](representing_information.md)
 - :material-arrow-decision: [**Vulnerability Management Decisions**](vulnerability_management_decisions.md)
+- :material-toy-brick-outline: [**Putting the Pieces Together**](decision_points_as_bricks.md)
 - :material-file-document-check-outline: [**Worked Example**](worked_example.md)
 - :material-checkbox-marked-outline: [**Evaluation**](evaluation_of_draft_trees.md)
 - :material-relation-one-to-many: [**Related Systems**](related_systems.md)

mkdocs.yml

@@ -22,6 +22,7 @@ nav:
       - Risk Tolerance and Priority: 'topics/risk_tolerance_and_priority.md'
       - Scope: 'topics/scope.md'
       - SSVC and Asset Management: 'topics/asset_management.md'
+    - Putting the Pieces Together: 'topics/decision_points_as_bricks.md'
     - Worked Example: 'topics/worked_example.md'
     - Evaluation: 'topics/evaluation_of_draft_trees.md'
     - Related Systems: 'topics/related_systems.md'