A new methodology that improves transparency, efficiency, and dynamism in the software planning, development, and reporting structure.
The goal of this report is to provide an alternative approach to software management where DevSecOps best practices are incorporated into an automated Government oversight process.
Great software documentation is a key to scaling and supporting Day 2 operations. The government typically manages this key component of enterprise software by mandating developers write laundry lists of static documentation in MS Word.
The practice of manually drafting, delivering, and reviewing stand alone documents has become an oversight burden within the DoD and it is constraining software delivery performance.
In typical DoD software programs, management by documentation has become the norm. Reports are used as a contractor oversight mechanism: deliver the report on-time with minimal errors and the Government is happy. This practice is reinforced by CDRLs.
What is a CDRL?
It stands for Contract Data Requirements List (CDRL), but in “government-speak” a CDRL is shorthand for any contractually mandated documentation (reports, drawings, source code, etc.). Management by CDRLs has negative cultural impacts to the government Program Management Office (PMO). These negative impacts must be addressed if the government is going to “own the tech stack”.
Oversight by CDRLs reinforces a bad habit of cubicle engineering. Cubicle engineering is where engineers are no longer building things, but spend up to 100% of their time going to meetings and reviewing / writing documents.
This behavior impacts the PMO culture because it draws focus away from delivering value to the warfighter. The Program Office spends too much energy focusing on tracking, reviewing, and correcting CDRLs vs. focusing that same energy on creating a fast feedback loop with their end users. Instead of oversight by CDRLs, contractor interaction should be a part of the daily software development process.
Software performance should be measured automatically using telemetry from software in production and software should be jointly developed between government and contractors.
To change the behavior of oversight by CDRLs, this development should occur behind a government firewall inside a government-owned source code repository; and documentation should be created automatically using modern software development tools, not in a static MS Word doc.
Bottom line: the government needs to adopt a services model where the government is part of the software development process
The CDRL oversight model needs to be replaced with a lean agile services model. To catalyze this change, PMO personnel must adopt a new oversight framework which is anchored in the use of real-time dashboards to manage software performance, both at functional and non-functional levels.
This new oversight framework will require an investment, but it pays for itself if the Program Office is willing to reinvest CDRL development costs into performance metric automation.
For example, it might cost $400K/year to build 20 static CDRLs¹ for a single software application. That money should be reinvested in automation. Instead of static reporting, PMO’s should establish a lean reporting model which can answer the following questions automatically:
- How well is my software providing value to the warfighter?
- How well are we managing costs?
- How well does this software fit inside the enterprise?
Below are the Top 10 CDRLs one would typically see in a DoD software development contract² along with an agile methodology for achieving the same outcome.
Software Development Plan (SDP)
CDRL Approach: Plan which provides insight into, and monitoring for, software development. Insight could include project schedules, organization, and resources.
Agile Approach: Government participation in sprint planning (or backlog grooming if using Kanban or XP). Reporting intent is met through government provided agile planning tools (Jira, Trello, Tracker etc.) which reside behind a government firewall.
Software Requirements Specification (SRS)
CDRL Approach: Document which specifies the requirements for a software product and the methods to be used to ensure each requirement has been met.
Agile Approach: Product teams are required to provide telemetry and metric gathering features inside their code base as part of an automated data collection effort. Metrics are tied to warfighter value and desired performance measures are documented as part of the capability need statement (see DoD 5000.87 for CNS information). These metrics are reviewed and updated as needed on a quarterly basis.
Source Code and Product Specification
CDRL Approach: Physical delivery often via the mail on a CD containing the executable software, score code, source files, and software support information including “as built” design information and compilation, build, and release notes of a software product.
Agile Approach: All new software is developed inside a government managed repository. Every release contains release notes that describe any functional changes to the code base. Any legacy software that is transitioning into a government managed repository is cloned into the repo as part of the software service. If data rights do not allow for source code delivery, this is considered a government technical debt issue and the software is a candidate for a greenfield effort.
Software Test Plan (STP)
CDRL Approach: Plan which describes the test environment to be used for testing, identifies the tests to be performed, and provides schedules for test activities.
Agile Approach: Government defines the expected testing strategy, how tests are defined, executed, and audited as part of the continuous integration/continuous delivery (CI/CD) process. Contractually enforce contractors to follow test-driven development processes at the unit with component, integration, API, and end-to-end tests as part of the contractors’ software development process. Government embeds the Development Test organization into software programs to verify compliance.
Software Test Report (STR)
CDRL Approach: Report which provides results of testing performed on a software system, normally delivered 30 days after testing.
Agile Approach: Enforce automated unit, component, integration, and API Tests as part of the contractors’ software development process. Government should embed the Development Test organization into software programs to verify compliance. Feedback from automated tests should be automatically available using CI/CD tools.
Software Version Description (SVD)
CDRL Approach: Document which describes a software version and the versions of components inside the software. It is used to release, track, and control software versions.
Agile Approach: Product teams are required to incorporate configuration as code practices (i.e. a release manifest in a YAML file which is part of the software product itself). The release manifest is updated in every software release.
Interface Control Description (ICD)
CDRL Approach: Document which provides a record of all interface information (such as drawings, diagrams, tables, and textual information) generated for the project.
Agile Approach: Require the team to use API description formats like the OpenAPI/Swagger Specification. Product teams leverage automated documentation processes tied to an automated API testing process. This makes it easier for teams to generate and maintain them. Any updates to API is documented in their release notes and teams maintain previous API support in accordance with any existing service level agreement (SLA) existing across the ecosystem. Mandate that product public APIs should use non-proprietary messaging formats and schemas.
Database Design Description (DBDD)
CDRL Approach: Document which describes the design of a database, and the software units used to access or manipulate the data. The DBDD is used as a basis for implementing the database and related software units. It provides the acquirer visibility into the design and provides information needed for software support.
Agile Approach: Teams are required to document database design description for their application in three core areas:
- The universal requirements for data (privacy, data retention, security, and reliance) are developed and delivered to the contractor. These universal non-functional requirements are automatically accessed in the CI/CD pipeline.
- Product teams are responsible for documenting their product’s data model and database operations. This includes a description of their data model and data description layer. The government should require all teams to use the same tool for building these architecture diagrams; a CDRL describing this process should be required.
- The embedded development test organization ensures basic database operations are well documented and supported by automated tests. These database operations include: start-up, shut down, backup, recovery, creating the tables, and inserting the database as part of their core project documentation. Any changes in software products database operations should be documented in the product’s release notes.
Software Architecture Description (SAD)
CDRL Approach: Document which provides drawings, diagrams, tables, and additional descriptions that comprise the authoritative description of software architecture for the program.
Agile Approach: Teams are required to document their architecture, apps dependencies, and data flows. The government should require all teams to use the same tool for building these architecture diagrams. Tool standardization will ensure the government has the ability to create an overall canvas for this architecture. Small software architecture teams which are government-led are responsible for keeping the enterprise software architecture canvas up-to-date.
Software User Manual (SUM)
CDRL Approach: Manual which provides end-user instructions on how to install a software product or subsystem. It also covers aspects of software operation, such as instructions for a particular position or task.
Agile Approach: Product teams required to follow UI/UX approaches and build software which operate as intuitively as possible. The government should review the team instructions for how to use the software during product demos and growth boards. Instructions should come in many forms including: in-app instructions, video tutorials, and help features within the code base.
The shift from oversight by CDRLs to using DevSecOps best practices as part of a lean reporting model will not happen overnight. The cultural and technical benefits will be well worth the investment. One disclaimer to the entire approach, it first requires you to establish a pocket of greatness within your organization that will drive change. My next article will be about “how to create talent density at the microlevel and how to scale it to the enterprise”. If your organization needs help getting its digital transformation off the ground please check out rise8.us, we have a dedicated group of engineers and change agents that would love to co-innovate with you.
- (20 CDRLs x 40 pg/doc (avg.) x 5 hrs/pg x $100/hr = $400K/yr)
- https://ncsx.pppl.gov/systemsengineering/Plans_Prodecures/DocumentationStandards/didlist.html and https://apps.dtic.mil/dtic/tr/fulltest/us/1014768