living documentation

Contributor(s): Cameron McKenzie

Living documentation is a dynamic method of system documentation that provides information that is current, accurate and easy to understand. Feature files that are written in a natural language format may serve as the core of living documentation. Each file describes how a particular piece of code is supposed to behave, gives an example and describes the desired outcome. Business stakeholders can review the documentation to ensure that it describes the desired behavior of the system from a logical standpoint. Developers can use the information to help them program only what is needed, making the code as lean as possible. Testers can use the documentation to help create tests and confirm that results meet requirements, and Operations can rely on the same information to support ongoing maintenance operations in the production environment.

The living documentation approach is commonly used with behavior-driven development (BDD) and specification by example (SBE). With these methodologies, executable specifications such as automated acceptance tests are often written in a way that permits them to serve as documentation. Because automated tests are run on a routine basis, any change in the software will necessitate a change in the living documentation. In this way, the process of testing ensures that the associated documentation is always up to date.

Content Continues Below
This was last updated in December 2014

Continue Reading About living documentation

Dig Deeper on Agile, DevOps and software development methodologies

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

We've been experimenting with having our docs live in GitHub, written in Markdown, and then using the native Git tools to manage pull-requests, change control, versioning, etc. And because it allows granular access-control, you can open up docs to outside groups to make edits (or suggest edits), allowing end-users to contribute back to making the products better. It requires some skills learning, but for basic editing of document/files, it's fairly simple to learn.
I like the idea of opening up the docs to allow outside groups to suggest edits. It's been my experience that most of the time, miscommunication between the business owner and developers ends up being the source of most headaches -- and the more opportunities to get that straight, the better.
Hard to talk about this without mentioning my own product, but OK, I'll risk it ;). Socialtext has been doing this for a decade, and our engineering team (including myself) runs most of its business processes on our own service (literally, we eat our own dogfood). While I feel we do a pretty good job here, overall the biggest challenge is when an organization has a lot of information to share. From there, living documentation is not enough. Curated living documentation, and easily searchable, becomes imperative. 
Living documentation is only 50% of what Margaret Rouse is talking about here. Living executable documentation is the other half. If your documentation is not driving your implementation it takes great discipline to keep both parts in sync. How do you know for sure that your documentation is really describing your applications' current behaviour? If the software behaves different from what you expect, is it a bug or is your documentation not up to date?

File Extensions and File Formats

Powered by: