Getting Started With Documentation-Driven Development

As developers we see documentation as a evil. However our end-users see it as a godsend.

It’s hard to bridge that gap between those two things. Our jobs tend to Involve taking a basic user story and converting that into Code. However there are huge benefits to having documentation generated before the actual code is written.

This allows you to speak in a common understanding about the future that you are about to add. When we only have a single sentence it’s hard to understand what it could mean.

Documentation during development is the process of starting development With a set of documentation and not a set of code. Generally speaking this documentation should be generated by the stakeholder that will be supporting the feature going forward. After the jet and documentation has been generated it is The source of truth that all other things should reference.

Documentation driven development has several steps involved but they’re all very basic.

1. Write documentation
2. Get feedback on documentation
3. Test-driven development (where tests align with documentation)
4. Push features to staging
5. Functional testing on staging, as necessary
6. Deliver feature
7. Publish documentation and increment versions

The following graph courtesy the NIST helps in visualizing how the effort in detecting and fixing defects increases as the software moves through the five broad phases of software development.

One can find analogy to test-driven development where, for every code change, associated unit tests have been written. Documentation-driven Development to be clear, is not aimed to replace test-driven development but rather augment this approach. Therefore this approach can be summarized as document-program-test-repeat.

The philosophy behind Documentation-Driven Development is a simple: from the perspective of a user, if a feature is not documented, then it doesn’t exist, and if a feature is documented incorrectly, then it’s broken.

Document the feature first. Figure out how you’re going to describe the feature to users; if it’s not documented, it doesn’t exist. Documentation is the best way to define a feature in a user’s eyes. Whenever possible, documentation should be reviewed by users (community or Spark Elite) before any development begins. Once documentation has been written, development should commence, and test-driven development is preferred. Unit tests should be written that test the features as described by the documentation. If the functionality ever comes out of alignment with the documentation, tests should fail. When a feature is being modified, it should be modified documentation-first. When documentation is modified, so should be the tests. Documentation and software should both be versioned, and versions should match, so someone working with old versions of software should be able to find the proper documentation. So, the preferred order of operations for new features:

Documentation traditionally is seen as a sort of journalistic endeavor. Doc writers are given some software, and they take it into the lab and poke it and prod it until they’ve figured it all out, then they write it down for everyone else to never read.

This misses the all-important process that happens naturally when a developer, idly sipping coffee one evening, drums up an idea for an application. The developer may not realize it, but as the idea formulates, there’s a kind of documentation happening already. Ideas don’t just appear fully formed with every detail mapped out in a tidy blueprint ready to be hooked up to lonely lines of code. Ideas happen gradually.