documentation/use-case-understanding-broken-branches

doc/_config.yml

@@ -20,6 +20,14 @@ aux_links:
   "OpenFastTrace on GitHub":
     - https://github.com/itsallcode/openfasttrace
 
+# GitHub edit link
+gh_edit_link: true
+gh_edit_link_text: "Edit this page on GitHub."
+gh_edit_repository: "https://github.com/itsallcode/openfasttrace"
+gh_edit_branch: "main"
+gh_edit_source: "doc"
+gh_edit_view_mode: "edit"
+
 # Heading anchor links
 heading_anchors: true
 

doc/terminology.md

@@ -33,6 +33,9 @@ A [specification item](#specification-item) that explicitly demands coverage by
 ### Deep Coverage
 Full coverage of a [specification item](#specification-item) including all its transitive providers down to [terminating specification items](#terminating-specification-item).
 
+### Direct Defect
+Coverage gap or error directly related to a [specification item](#specification-item) itself, such as missing, outdated, predated, or unwanted coverage.
+
 ## F
 
 ### Forwarding
@@ -56,7 +59,7 @@ Content that defines [specification items](#specification-item) or coverage link
 ### OpenFastTrace
 The requirement tracing tool suite.
 
-## OFT
+### OFT
 
 See [OpenFastTrace](#openfasttrace)
 
@@ -88,7 +91,7 @@ The unique name part of a [specification item ID](#specification-item-id).
 ### Specification Item Revision
 Number in the [specification item ID](#specification-item-id) used to invalidate coverage when an item's meaning changes.
 
-## SRS
+### SRS
 
 See [System Requirement Specification](#system-requirement-specification)
 
@@ -107,7 +110,7 @@ Label for categorizing [specification items](#specification-item), used for filt
 A [specification item](#specification-item) that does not require further coverage (e.g., code, tests).
 
 ### Transitive Defect
-Coverage gap caused by an undercovered provider in the trace chain.
+Coverage gap caused by an [undercovered](#undercovered) [provider](#coverage-provider) in the trace chain.
 
 ## U
 

doc/user_guide/use_cases/understanding_and_fixing_broken_requirement_branches.md

@@ -1,8 +1,25 @@
+---
+layout: default
+title: Understanding and Fixing Broken Requirement Branches
+parent: Use Cases
+grand_parent: User Guide
+nav_order: 9
+---
+
 ### Understanding and Fixing Broken Requirement Branches
 
-Requirements — or specification items as we call them more broadly — in OFT are internally organized in a graph. If you haven't heard of that term, don't worry. In most cases it is close enough to think of the relationships between the specification items like a forest where the highest level of the specification are tree trunks from which details branch out into big branches, twigs and eventually leaves.
+Requirements — or [specification items](../../terminology.md#specification-item) as we call them more broadly — in OFT are internally organized in a graph. If you haven't heard of that term, don't worry. In most cases it is close enough to think of the relationships between the specification items like a forest where the highest level of the specification is tree trunks from which details branch out into big branches, twigs and eventually leaves.
+
+Requirement engineering calls this the "traceability matrix". That term is a bit clunky, but we thought you should have heard of it at least once.
+
+#### Direct and Transitive Defects
+
+When analyzing the health of your traceability graph, OFT distinguishes between two types of defects:
+
+*   **[Direct Defect](../../terminology.md#direct-defect)**: A coverage gap or error that is directly related to the item you are looking at. For example, if a requirement needs design coverage, but none is provided, or if the provided coverage is outdated or predated.
+*   **[Transitive Defect](../../terminology.md#transitive-defect)**: A coverage gap that originates further down the trace chain. The item you are looking at may have perfectly valid direct coverage, but one of its [coverage providers](../../terminology.md#coverage-provider) (or one of *their* providers) has a defect.
 
-Requirement engineering calls this the "traceability matrix". That term is a bit clunky, but we thought, you should have heard of it at least once.
+In the tree analogy, a direct defect is like a leaf being missing or improperly attached to a twig. A transitive defect is like a leaf being perfectly attached to a twig, but the twig itself is broken off from the branch.
 
 #### Everything That can go Wrong…
 
@@ -15,11 +32,11 @@ Unfortunately, we are only human, and humans make mistakes. Here is a non-exhaus
 | Unimplemented feature           | missing leaves in the implementation               |
 | Missing tests                   | missing leaves in the test                         |
 | Typos in requirement IDs        | causing branches to be cut somewhere in the middle |
-| Wrong artifact type in coverage | both missing and unexpected coverage               |
+| Wrong [artifact type](../../terminology.md#artifact-type) in [coverage](../../terminology.md#coverage) | both missing and unexpected coverage               |
 
 #### Reading and Understanding the Link Error Types
 
-Depending, from where you look at a specification item, it can have links that point towards it (incoming) or away from it (outgoing). And those links can be broken. This is a typical sign that the requirement matrix contains wrong coverage, is incomplete or has excess parts.
+Depending on where you look at a [specification item](../../terminology.md#specification-item), it can have links that point towards it (incoming) or away from it (outgoing). And those links can be broken. This is a typical sign that the requirement matrix contains wrong coverage, is incomplete or has excess parts.
 
 #### Outgoing Link Statuses
 
@@ -34,13 +51,13 @@ Depending, from where you look at a specification item, it can have links that p
 
 "Covers" means everything is fine.
 
-When the outgoing link from this item is "predated", that means it points to a newer version of the covered item than it should. This is usually a typo that you need to simply fix. On rarer occasion it can hint at a merge error or a problem when multiple teams contribute to the same specification. Check the document history if unsure.
+When the outgoing link from this item is "predated", that means it points to a newer version of the covered item than it should. This is usually a typo that you need to simply fix. On rare occasions it can hint at a merge error or a problem when multiple teams contribute to the same specification. Check the document history if unsure.
 
-"Outdated" coverage typically happens when an existing specification item was updated, but the coverage wasn't. This is one of the most useful safeguards in OFT.
+"Outdated" coverage typically happens when an existing [specification item](../../terminology.md#specification-item) was updated, but the [coverage](../../terminology.md#coverage) wasn't. This is one of the most useful safeguards in OFT.
 
 Copy & paste often leads to "ambiguous" coverage, where two items are defined with the same ID. Treat this like you would fix a typo, but be careful, if the ID wasn't updated, then there are likely other copy & paste errors hiding in the vicinity. 
 
-Coverage is "unwanted" when the specification item that it points to didn't ask for it. Check for typos in both IDs. The most common mistake here is that either the required artifact types or the coveraging artifact types are wrong.
+Coverage is "unwanted" when the [specification item](../../terminology.md#specification-item) that it points to didn't ask for it. Check for typos in both IDs. The most common mistake here is that either the required [artifact types](../../terminology.md#artifact-type) or the coveraging artifact types are wrong.
 
 "Orphaned" finally means that this item claims to cover a requirement that does not exist. Or ceased to exist. In this case first check for typos, and if it is not a typo, check the history of the documents to see if there is maybe coverage left for something that has been obsoleted higher up in a specification.
 
@@ -54,19 +71,19 @@ Coverage is "unwanted" when the specification item that it points to didn't ask
 | Covered Predated | This item is covered by another item that specifies a newer revision     | ❌  |
 | Covered Outdated | This item is covered by another item that specifies an older revision    | ❌  |
 
-If you see "covered shallow" on an incoming link, this means that there is at least one specification item providing the required coverage.
+If you see "covered shallow" on an incoming link, this means that there is at least one [specification item](../../terminology.md#specification-item) providing the required [coverage](../../terminology.md#coverage).
 
-"Covered unwanted" means that another item covers the one you are looking at, but it shouldn't, because that coverage was not required. In most cases you are looking at a copy & paste error. Sometimes it is simply a typo in the artifact types. In rarer circumstances this happens the person who wrote the higher level item disagreed with the one who did the coverage. The last variant can be solved by talking to each other.
+"Covered unwanted" means that another item covers the one you are looking at, but it shouldn't, because that coverage was not required. In most cases you are looking at a copy & paste error. Sometimes it is simply a typo in the [artifact types](../../terminology.md#artifact-type). In rarer circumstances this happens the person who wrote the higher level item disagreed with the one who did the coverage. The last variant can be solved by talking to each other.
 
-"Covered predated" means some other specification item claims to cover a newer version of this item than is currently present in the spec. "Covered outdated" is the opposite situation. The problem resolution is the same as in the [section above](#outgoing-link-statuses) where the predated and outdated incoming links were discussed.
+"Covered predated" means some other [specification item](../../terminology.md#specification-item) claims to cover a newer version of this item than is currently present in the spec. "Covered outdated" is the opposite situation. The problem resolution is the same as in the [section above](#outgoing-link-statuses) where the predated and outdated incoming links were discussed.
 
 #### Bidirectional Link Statuses
 
 | Status           | Explanation                                                              | Ok |
 |------------------|--------------------------------------------------------------------------|----|
 | Duplicate        | Two items have the same ID                                               | ❌  |
 
-Duplicate links are special. They don't have a clear direction, since OFT cannot tell which specification item is the original and which one is the duplicate. In either case, you are most likely looking at a copy & past error again. Handle this with care and check if you maybe forgot to adapt other aspects of the copy too, not only the ID.
+Duplicate links are special. They don't have a clear direction, since OFT cannot tell which [specification item](../../terminology.md#specification-item) is the original and which one is the duplicate. In either case, you are most likely looking at a copy & past error again. Handle this with care and check if you maybe forgot to adapt other aspects of the copy too, not only the ID.
 
 ---