Maybe it’s time we re-think docs

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 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?