[simmschi]

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.

[danny_codes]

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.

[Raidion]

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.

[wpietri]

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.

[hitchstory]

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.