Chapter 4.3 follows chapter 4.2, The six documentation artifacts, and precedes chapter 4.4, Physical differences between the rungs, within part 4, the profile library.
4.3.1 Ladder position of the documentation profiles
The documentation ladder orders doses from a stripped build to a full manual set. A dose is a defined amount and kind of documentation attached to the same executable source. Each higher rung carries the permitted material of the lower rungs and adds a new kind of evidence. A rung permits its own material and forbids material reserved for later rungs.
The stripped build, a build with its documentation removed, is the lowest documentation level. It carries no documentation. The first rung adds orientation through root, folder, and source headers. The next rung adds a header to every source module. The next rung adds body comments at meaningful points. The next rung adds a traceability file, high-risk trace anchors, and an entry-point index. The next rung extends trace anchors to every traced site and adds a test-to-requirement map. The next rung adds decision notes and a relationship ontology. The next rung adds a relationship map and diagnostic comments. The final rung adds a User Manual and a Developer Guide.
Payload is documentation measured against the unchanged executable source. The measurement is cumulative. The entry-point index is a placement artifact and is measured separately from payload. All documentation remains inert: it changes neither execution nor test results.
4.3.2 Dose boundaries of the documentation profiles
The ladder uses these boundaries for permits and prohibitions.
Stripped build. The floor permits executable source without documentation. It forbids every documentation artifact.
L1. Orientation permits location guidance in root files, folder files, and source headers. It forbids module-wide headers, body comments, trace material, decision notes, relationship material, and manuals. source: 3. The LAP Profiles.md line 78
L1H. Module headers permit a short orientation header in every source module. It retains the orientation rules of the preceding rung. It forbids body comments, trace material, decision notes, relationship material, and manuals. source: 3. The LAP Profiles.md line 108
L2C. Body comments permit explanations of behavior and local mechanics at meaningful code points. It forbids trace anchors, traceability files, relationship maps, decision notes, and manuals. source: 3. The LAP Profiles.md line 120
L2S. Selective traceability permits high-risk trace anchors, a traceability file, and an entry-point index. It forbids ordinary body commentary, decision notes, relationship maps, and manuals. source: 3. The LAP Profiles.md line 135
L2T, level two total traceability, complete linking of every traced site to its requirement and test. It permits trace anchors at every traced site and a map from tests to requirements. It retains the selective traceability material. It forbids decision notes, relationship maps, probe comments, and manuals. source: 3. The LAP Profiles.md line 157
L3B. Decision evidence permits decision notes and a relationship ontology. It retains the lower-rung material. It forbids the relationship map, probe comments, and manuals. source: 3. The LAP Profiles.md line 177
L4P. Relationship evidence permits a relationship map linking symptoms with causes and probe comments. It retains the lower-rung material. It forbids manuals. source: 3. The LAP Profiles.md line 197
L5P. Manual guidance permits a User Manual and a Developer Guide. It retains the lower-rung material and has no payload target. It forbids no later artifact because it is the final rung. source: 3. The LAP Profiles.md line 217
4.3.3 Rung examples of the documentation profiles
Stripped build example. A build containing only executable source is normative. Adding a readme file is an anti-example because orientation belongs to the first rung. source: 3. The LAP Profiles.md line 78
L1 example. A root readme file that directs a reader to the main folders is normative. A decision note explaining a design choice is an anti-example because it belongs to a later rung. source: 3. The LAP Profiles.md line 88
L1H example. A short orientation header in every source module is normative. A body comment that explains local mechanics is an anti-example. source: 3. The LAP Profiles.md line 108
L2C example. A comment beside a meaningful branch that describes its local behavior is normative. A traceability file mapping a requirement to that branch is an anti-example. source: 3. The LAP Profiles.md line 120
L2S example. A selective trace record at a high-risk site is normative. A decision note in the same dose is an anti-example. source: 3. The LAP Profiles.md line 135
L2S has a measured payload of 3.114 percent against a target of 3.0 percent, with sidecar files of 7,894 bytes. source: 3. The LAP Profiles.md line 138
L2T example. A trace anchor at every traced site, paired with a test-to-requirement map, is normative. A relationship map is an anti-example. source: 3. The LAP Profiles.md line 157
L2T has a measured payload of 3.815 percent against a target of 4.0 percent, with sidecar files of 14,268 bytes. source: 3. The LAP Profiles.md line 160
L3B example. A decision note that records the reason for a code shape is normative. A symptom-to-cause relationship map is an anti-example. source: 3. The LAP Profiles.md line 177
L4P example. A probe comment linked to a relationship between a symptom and a cause is normative. A user manual is an anti-example. source: 3. The LAP Profiles.md line 197
L5P example. A User Manual and a Developer Guide that describe use and maintenance are normative. A manual that changes executable behavior is an anti-example. source: 3. The LAP Profiles.md line 217
4.3.4 Worked example of the documentation profiles
The worked example shows a selective traceability dose with its permitted evidence and a forbidden later artifact.
Worked example of a selective traceability dose.
# Selective trace anchors remain at high-risk sites.
# traceability file maps requirements to code.
# Decision notes and relationship maps remain forbidden.4.3.5 Permit and forbid matrix
The matrix compares each rung by purpose, permitted artifacts, and forbidden artifacts. It separates cumulative material from material reserved for later doses.
Figure D-L2-2. A permit and forbid table comparing the purpose, permitted artifacts, and forbidden artifacts for every documentation rung.
%% figure D-L2-2 flowchart LR subgraph g1[" "] n1["A permit and forbid table comparing the purpose<br/>permitted artifacts<br/>forbidden artifacts for every documentation rung"] end
source: operations/site-ia/A3-diagram-specification.md
source: 3. The LAP Profiles.md line 240
Permit and forbid table for the documentation ladder.
4.3.6 Source ownership of the documentation profiles
The owning material is distributed across the profile folders. The profile rules in those folders supply the stripped floor and the rung excerpts used here.
source: operations/site-ia/A6-page-briefs.md section ”# L2.”