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.

Agile coach and developer. Follow me on Twitter: https://twitter.com/BertilMuth

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store