Fair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that.

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.

I think most of us approach documentation without intention. We write to express the idea, but fail to consider how the documentation fits into the deliverable.

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.

Code is more complex than documentation specifically because it needs to deal with every issue. If you're going to cover every edge case in documentation, just write the code. Tools like OpenAPI/Swagger blur the lines.

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.

Sure. But where some see the lack of updates as some sort of moral failure, I think it's usually a sign that there is a process problem. The documentation was supposed to solve some sort of problem, but the fact that people don't update it is usually a sign that either it wasn't a real problem, that documentation wasn't the right solution, or that there's a broken feedback loop in the team's process.

I built this documentation/testing framework to do just that: https://hitchdev.com/hitchstory

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.

I am familiar with the notion that programmers are people who turn documents into code. I just think it's rarely true and even more rarely necessary.

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.