Docs-as code: arc42, AsciiDoc, Gradle & Co. combined

[@RagdollRocket]

The problem is that you always have to deal with outdated docs because no dev wants to maintain docs with every single code change. How about creating docs from your unit tests automatically, which are always up to date because your tests have to pass in order to deploy?

[@ralfdmueller]

sorry, I didn't get a notification for your comment, so I only noticed it now. You are absolutly right. Docs need to be maintained. Nobody wants to read outdated docs. Your approach to use unit tests for the docs is the right way but it only works for code. For other parts of the docs, we have to find different solutions. A good start is to try to document in such a way (abstraction level) that chances are that it does not get outdated soon (do not document too much details). But it is still hard to keep the docs up-to-date and acurate. Nevertheless, my experience shows that the docs-as-code approach helps to make a step forward in the right direction.