Comprehensive Documentation Assurance Protocol

Documentation is the primary deliverable – code is merely an artifact of the documentation process!

Other frameworks treat documentation as a secondary concern – something generated after the code is written, if generated at all. SADMF recognizes that code without documentation is an unverifiable claim. Anyone can write code that appears to work. Only documentation proves that the code was intended to work the way it does, that the appropriate authorities approved it, and that the person who wrote it understood what they were doing.

Before a Code Engineer writes a single line of code, they must complete a 12-page Change Impact Assessment (CIA). The CIA documents the proposed change in exhaustive detail: the business justification, the technical approach, the files that will be modified, the estimated number of lines added and removed, the potential impact on every other feature in the current Convoy, and a risk assessment scored against the SADMF Risk Taxonomy (17 risk categories, each rated on a 5-point severity scale). The CIA must be approved in sequence by the Feature Captain, the Code Standards Enforcement Team (CSET), the Enterprise Architecture Review Board (EARB), and the DevOps Usage & Compliance Head Engineer (DOUCHE). Approval in sequence means that each approver reviews the document only after the previous approver has signed. Parallel approval is not permitted because later approvers need the context of earlier approvers’ comments to make informed decisions. The sequential approval process typically takes 2-3 weeks, during which the Code Engineer is expected to remain available for questions but is not permitted to begin coding.

Upon CIA approval, the Code Engineer may begin writing code, but the documentation requirements do not end. Every method must have an accompanying Method Specification Document (MSD) that describes the method’s purpose, inputs, outputs, side effects, and the section of the CIA it implements. The MSD is reviewed by the CSET during Code Inspection alongside the code itself, and a method without a corresponding MSD is treated as undocumented code, which is functionally equivalent to unauthorized code. After coding is complete, the Code Engineer must produce a Post-Implementation Verification Document (PIVD) that describes what was actually built, how it differs from the CIA (if at all), and why any deviations occurred. Deviations without documented justification are flagged as process violations.

The CDAP documentation suite – CIA, MSD, and PIVD – is stored in the Documentation Repository, a separate version control system from the code repository. This separation is intentional: code and documentation have different lifecycles, different approval chains, and different audiences. Code is for machines; documentation is for auditors. The Documentation Repository is maintained by a dedicated Documentation Coordinator role within the System of Authority (SOA), who ensures that every document is properly versioned, cross-referenced, and archived. The Documentation Coordinator also produces the monthly Documentation Completeness Report, which tracks the ratio of documented to undocumented code changes. A ratio below 100% triggers an automatic escalation to the Admiral’s Transformation Office (ATO).

Critics of CDAP sometimes observe that the documentation process adds significant time to the delivery cycle. This observation is correct and is precisely the point. Documentation time is thinking time, and thinking time prevents defects. A Code Engineer who spends two weeks documenting a proposed change will inevitably discover flaws in their approach that would have become defects in production. The documentation process is, in effect, a form of static analysis performed by humans – slower than automated tools, certainly, but more thorough and more aligned with the SADMF principle that human judgment must never be replaced by automation. The CDAP ensures that when code finally reaches production, it arrives with a complete paper trail that proves the organization knew exactly what it was deploying and chose to deploy it deliberately.

See Also