Designing Tech

Documentation Driven Change (DDC)

Brandon Gillespie

Jun 14, 2016 • 3 min read

A monumental task in the technology industry is to get good Execution Documentation. It is such a challenge that most systems do not even have it, or if it does exist, it is a pale shadow in contrast to what is actually implemented. This becomes a great challenge when bringing new staff onboard, transitioning work efforts between teams and team members, or even dealing with a disaster scenario.

Most engineering efforts actually work in an iterative “agile” manner, even if they are not managed as an Agile project. This is because the most common approach in engineering and “figuring out” a solution do so by trial and error, not by referencing somebody else's blueprints. When implementation happens in this manner of just “figuring it out”, the last thing somebody wants to do after having wrestled through hours of implementation is to go back and write down how it was done; and frankly speaking, many of the steps taken to get to completion are likely forgotten. If the Execution document happens at all, it is commonly an afterthought, and much of the requisite fidelity of detail is lost in the rear-view mirror of the situation.

Documentation Driven Change (DDC) is a simple and effective way to create good Execution documentation in an Agile world. DDC is not merely implementing a formal Change Control process (such as . DDC documentation could be used in an ITIL Change Process, but that is beside the point. Furthermore, with server automation documenting change becomes even more curious. However, DDC can be the driving force behind exploration efforts, and the resulting document can become a basis for new automation.

DDC follows in the footsteps of software development's TDD, where the desired result must first be described with a test, then the software is written to match the test. With DDC, a document begins by describing the expected outcome, and it is then expanded with the explicit code, steps, commands, and actions to bring the change to fruition. Ideally, the commands are typed into the document first, and then cut-and-pasted into the actual system where the change is happening. While this may seem like simple logic, the pragmatic reader will know it is opposite of how most IT implementations work, despite what processes may exist.

For example, an administrator is tasked in figuring out how to do hot backups for a new MariaDB server. Using DDC, the administrator opens a working document and labels it for the specific action “MariaDB Hot Backups.” Then, as they research and learn information, they paste into this document the steps they want to first try. These might be:

Setup backup space for hot backups. (Include a link to the “Adding Backup Disk document”)

Download latest copy of hot-backup software into org system repository, such as:

 cd /repo/base/path
 curl -kO https://remote.repo/software.v.12.rpm
 createrepo .

On destination server, install hot-backup software from org repository:
```
 yum -y install hot-backup-software
```

And so forth. Then, the administrator attempts to execute on their own drafted plan. This usually is met with some things not working as expected, and the documentation is updated before the next iteration, becoming more and more refined until it represents the final product.

The key to DDC is to keep the documentation as lightweight as possible, both in creation and sustainability. Setting up screen shots is less desirable than simply referencing the steps that should be taken, such as:

Select the File Menu, then Open->Task list and check [New Tasks]

The DDC should not necessarily be an authoritative source. In the world of highly advanced system automation, DDC can simply be the first step to making an automation service.

Good DDC documentation has a few elements:

Replay Ability: It can be handed to somebody else with an equal level of technical aptitude as the original author, and that second individual can reproduce the results.
Simple: if the execution document is littered with too much information and pages of screen shots, it is probably too difficult to sustain, let alone easily read and follow.
Cut-and-Paste: blocks of control commands are identified easily, and formatted so they can be cut-and-pasted.
Do not include prompts (i.e. $ command is less useful than simply command ).
CLI interfaces are easier to document and replay than GUI
When referencing a GUI, keep it simple. Describe the GUI action, rather than using screenshots, such as:
Select the File Menu, then Open->Task list and check [New Tasks]

As with any tool, there is a right place and time. With automation services, the role of DDC becomes even more relevant. Simply saying “my documentation is my automation” is not valuable, as often times the automation is normalized and abstracted into a wide variety of templates and objects. This makes it very difficult for a person to read through the automation system to figure out how something works, unless they have a degree in technology archaeology. The DDC documentation, however, can be the first step that leads to automation, and it can be updated when major changes to the system are needed.