The lingua franca of ideas is natural language.
Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best.
Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.
For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an implementation detail.
I think software as a discipline is distinctly undiscipled about these sorts of concepts.
Documentation is useful when it's job is to help understand why the code is the way it is, what problems are trying to be solved, and what constraints the devs had.
I realized one day that the specs, tests and how-to markdown documentation I wrote all used the same examples.
From that I derived the idea to create a "spec" DSL that could both be run as a test and generate markdown (with screenshots, etc.) to make nice high level how-tos.
Cucumber has the same sort of idea but the DSL really isn't suitable.
Personally, I don't think documents have intent. People have intent. Sometimes they write down some words as an approximate way to communicate their intent in that moment. But if there is a conflict between the written document and the actual intent, it's the human intent that matters.
I also think that drift between written description and actual intent is good and desirable, because it usually means that the humans learned something about what actually needs to happen. So to the extent that documentation acts as leg irons for intent, I'm generally opposed to it. The faster our teams learn, the better the things we make.
