Keeping them updated as the code changes is difficult. I’m finding as docs are separate repos disconnected from the source. Not sure how to easily keep it all in sync
That was the premise of literate programming: interweave the docs with the code, and developers would find it frictionless to keep the docs updated.
The challenge I ran into is scaling it up. There isn’t an “aspect-oriented, single source multiple output literate programming” implementation yet. So if you were a developer, you see the code and code docs. If you were new to the codebase, then you could switch to an “architecture” aspect or “design” aspect, and see different docs that still link back to relevant code blocks. If you were a technical writer maintaining user docs, you would switch to a “user manual aspect” that still linked back to relevant code blocks. Same for operations manager, support team member, and so on.
We do this linking back all by hand today, and the mental model people build up in their heads and across a Net-mediated consensus to establish the link mostly evaporates when the issue at hand is addressed. I wouldn’t B&D require linkage, but it sure would be nice to have memorialize linkages for specific issues, discussions, and so on.
We express most of the metadata today, there isn’t a system I’ve found yet that captures it in a low-friction manner.
I was able to link docs with functional tests at one point. That made more sense and it scaled to a degree. You definitely need a way to include or exclude chunks of tests from code examples, because the bootstrapping in tests doesn’t match production code very often.
I think you first have to link the docs to the code. Once that is done you have a certain amount of automatic doc generation, but more importantly the ability to warn in the opposite direction: you wrote this block of code and this documentation at the same time. You just changed the code that accompanied this doc, but didn’t update the docs. You sure about that?
Both in corporate and open source settings, I find the most difficult part of documentation to be how to organize it. There is a huge amount of good information out there, but it's incredibly difficult to find. I have this problem as a user all the time, but even when I'm creating the docs I'm not sure how to make them more accessible.
