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.