You wrote: The Agile Manifesto values “working software over comprehensive documentation.”
Bradley Ross
11

Hi Bradley. Thanks for answering.

My message is NOT: don’t do documentation. Finding the right balance between too much and too little is important, I agree with you.

My message is: code is the most reliable documentation of the software’s behavior.

For example, I provide Javadoc documentation for my requirementsascode project. I fell into the exact trap that I describe in the article: I refactored the code, and noticed later that the Javadocs were out of sync with the code. They were no longer describing the behavior accurately.

Now, what did I do, throw out the Javadocs? Could have. But I decided that keeping this documentation for the users was worth the effort of keeping it in sync with the code. That’s the trade-off one needs to make. Beware of the risk of outdated documentation.

Concerning your comments on requirementsascode: if is mostly focused on what I describe in chapter 1 of the article, the use cases.

The neat – and a bit innovative – thing about it is that it works similar to a statemachine on the inside, but lets you extract human-readable documentation from the code, in the form of use case narratives.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.