Merge pull request #45 from cdfoundation/toc-cleanup

Clean up pass for issue #44

content/en/learn/cd/_index.md

@@ -11,7 +11,7 @@ description: >
 - [Continuous Delivery and Deployement](#heading-cdd)
 - [Definition](#heading-def)
 - [Description and Scope](#heading-das)
-- [Best practices](#heading-bp)
+- [Best practices in Action](#heading-bp)
 
 
 # Continuous Delivery and Deployment {#heading-cdd}
@@ -32,7 +32,7 @@ Continuous deployments can be viewed in two ways, a push process or a pull proce
 
 
 
-# Best Practices {#heading-bp}
+# Best Practices in Action {#heading-bp}
 
 ## Repeatability {#heading-repeat}
 The deployment process must be repeatable across all stages of the pipeline. To achieve repeatability, values that are specific to an environment should be separated from the deployment tasks. This allows the logic of the deployment to remain consistent, while the values change according to the endpoint. 

content/en/learn/ci/_index.md

@@ -6,20 +6,18 @@ description: >
   Best practices for continuous integration
 ---
 
-- Definition
-- Why it matters
-  - Associated DORA capabilities
-- Key stakeholders
-- Best practices
-- Relationship to other practices
+- [Why Continuous Integration](#heading-wci)
+- [Definition](#heading-def)
+- [Description and Scope](#heading-das)
+- [Best Practices in Action](#heading-bp)
 
 
-# Why Continuous Integration
+# Why Continuous Integration {#heading-wci}
 
 Continuous Integration ensures that coding changes are merged, compiled/linked, packaged and registered frequently, avoiding broken builds and ensuring a clean release candidate is available continuously. 
 
 
-# Definition
+# Definition {#heading-def}
 [Continuous Integration](https://github.com/cdfoundation/glossary/blob/main/definitions.md#continuous-integration), the CI in CI/CD, is the practice of combining code changes frequently, where each change is verified on check-in.
 
 - Examples of verifications:
@@ -28,7 +26,7 @@ Continuous Integration ensures that coding changes are merged, compiled/linked,
   - Building and packaging
 
 
-# Description and Scope
+# Description and Scope {#heading-das}
 Minimizing broken builds due to incompatible coding changes is the purpose of the continuous integration process. Historically, project teams would have a ‘sync-up’ process which generally meant check-in all of your coding updates and hope that the build runs. An unsung hero called the Build Manager created the build script which would include merging and pulling all of the coding updates based on ‘tags’ and then get the build to run. 
 
 This ‘sync-up’ step was performed once a week, every two weeks or monthly. It was not unusual for the build manager to put in a solid 8-12 hours to get the build working. The resulting build was often referred to as a ‘clean’ build which created an available release candidate. This process meant you would only have a release candidate to pass to testing on a very low frequency basis, which in turn slowed down the entire application lifecycle process. Builds were always the bottleneck. 
@@ -40,7 +38,7 @@ The process of triggering the ‘build’ is sometimes referred to as the contin
 As CI matured, so did the process around the central theme. CI workflows were created by developers to not only run the build script, but also deploy the new binaries to a development endpoint followed by running automated testing. In addition, code and library management steps were added to the build improving the quality and security of code, and ensuring the usage of the correct transitive dependencies, open source licenses, and security scans were done during the creation of the release candidate.   
 
 
-# Best Practices
+# Best Practices in Action {#heading-bp}
 ## Merging
 In your build step, it is important to understand what code is being pulled from version control to be assembled into a discrete deliverable. For this reason, there should be clear best practices defined for managing branches. 
 
@@ -69,5 +67,5 @@ Build parameters determine how the resulting binaries are created. For example,
 ## Binary Repository
 The CI build should include the updating of the binaries to an appropriate binary repository. The binary repository should be used to persist and share the binaries to the continuous deployment step of the Continuous Delivery Pipeline. These binaries should be tagged with the corresponding version control ‘tag.’  
 
-# Docker Specific Best Practices
+## Docker Specific Best Practices
 A Multi-stage Docker Build is the process of moving your CI steps into a container build. It is called ‘multi-stage’ because it aggregates all of the needed steps into a Docker Build of the image. For example, in stage one run the compile/link steps to create the artifacts, stage two copy the artifacts to a run-time and destroy stage one. The benefit of considering a Multi-stage Docker Build is to create an airtight environment in which the process is executed. The container holds all objects without the possibility of an external change. Interesting to the Multi-stage process is the ability to move your entire CI Build process into a single container build. Best practices related to each of those steps should still be followed. This option minimizes external updates to the build step making it a best practice candidate. 

content/en/learn/config/_index.md

@@ -9,9 +9,9 @@ description: >
 
 
 - [Why Configuration Management](#heading-wcm)
-  - Associated DORA capabilities
 - [Definition](#heading-def)
-- [Best practices](#heading-bp)
+- [Description and Scope](#heading-das)
+- [Best practices in Action](#heading-bp)
 
 # Why Configuration Management {#heading-wcm}
 Configuration Management maintains a record of the state of software and runtime environments with changes overtime. Configuration management tracks the many attributes and conditions of how software is assembled, how environments are defined, and records updates allowing systems to be consistently maintained by presenting a history of state changes.  
@@ -36,7 +36,7 @@ Microservices adds a new layer of configuration challenges. Because each are sma
 
 Lessons from the past instruct us to begin automating the configuration management and change tracking of the full IT stack. Adding automated configuration management into the CD pipeline will become increasingly important as companies decompose applications into hundreds of independent functions running across dozens of clusters. 
 
-# Best Practices {#heading-bp}
+# Best Practices in Action {#heading-bp}
 ## Dependency Management
 Core to configuration management is understanding the relationships between objects. The ability to easily see relationships between artifacts, objects and environments is essential. Dependency management enables the view of the relationships from an artifact to a version of an application, from application version to the artifacts that compose it and from an environment to the application versions that run in the environment. 
 ## Library Management

content/en/learn/testing/_index.md

@@ -10,11 +10,9 @@ description: >
 
 
 - [Why Continuous Testing](#heading-wct)
-  - Associated DORA capabilities
 - [Definition](#heading-def)
-- Key stakeholders
-- Best practices
-- Relationship to other practices
+- [Description and Scope](#heading-das)
+- [Best Practices in Action](#heading-bp)
 
 # Why Continuous Testing {#heading-wct}
 ## Find issues fast
@@ -38,10 +36,10 @@ Getting fast feedback on the impact of changes throughout the software delivery
 Because testing is so essential, we should be continuously performing all types of testing as an integral part of the development process.
 Not only does this help teams build (and learn how to build) high-quality software faster; DORA's research shows that it also improves software stability, reduces team burnout, and lowers deployment pain.
 
-# Description/Scope
+# Description and Scope {#heading-das}
 All types of automated testing (unit, integration, acceptance, etc) should be run against every commit to version control to give developers fast feedback on their changes. Developers should be able to run automated tests as much as possible on their workstations to triage and fix defects. Testers should be performing exploratory testing continuously against the latest builds to come out of CI stage.
 
-# Best Practices
+# Best Practices in Action {#heading-bp}
 ## Manual Testing
 Allow testers to work alongside developers throughout the software development and delivery process. Note that "tester" is a role, not necessarily a full-time job. Perform manual test activities such as exploratory testing and usability testing both as a way to validate existing automation and also identify opportunities to extend test coverage.  Many products, especially those with a complex graphical interface, will not be able to achieve 100% automated test coverage, so it's important to have strong domain expertise in testing strategies.