> It's like code... code can be out of date after a while, too. The question is how easy it is to keep it updated and current. I think that's the biggest argument behind diagrams as code.
I agree that documentation is nice even with the maintenance burden, but most would be surprised at just how much outdated code is out there. If many struggle to keep even their code up to date and not full of CVEs, what makes you think that they will also be able to have up to date documentation?
> Imagine you throw away your codebase each time you deploy your executable.
Honestly, I'm tempted to do this sometimes.
For example, consider splitting up monoliths and replacing them with many smaller services. If there is a problem with updating one part of the system, it can be left to slowly rot in the backlog, until it becomes a priority, at the same time without blocking doing the things that matter in the other parts of the system. Code should be not just easy to read and change, but also throw away. Not only that, but some more modern frameworks are just less painful to work with than the old ones (e.g. no more XML configuration hell) and you also often realize that you can do things better than the first implementation.
In a sense, one can say the same about docs: make it a Markdown file when you need to write something down, that can be easily changed/replaced and included with a merge/pull request, as opposed to some 50 page .docx file with no version control in some random network drive subdirectory.
I agree that documentation is nice even with the maintenance burden, but most would be surprised at just how much outdated code is out there. If many struggle to keep even their code up to date and not full of CVEs, what makes you think that they will also be able to have up to date documentation?
> Imagine you throw away your codebase each time you deploy your executable.
Honestly, I'm tempted to do this sometimes.
For example, consider splitting up monoliths and replacing them with many smaller services. If there is a problem with updating one part of the system, it can be left to slowly rot in the backlog, until it becomes a priority, at the same time without blocking doing the things that matter in the other parts of the system. Code should be not just easy to read and change, but also throw away. Not only that, but some more modern frameworks are just less painful to work with than the old ones (e.g. no more XML configuration hell) and you also often realize that you can do things better than the first implementation.
In a sense, one can say the same about docs: make it a Markdown file when you need to write something down, that can be easily changed/replaced and included with a merge/pull request, as opposed to some 50 page .docx file with no version control in some random network drive subdirectory.