[erikerikson]

The integration work is what's hard. Just like it's easier to cut new code and harder to resolve conflicting needs in two existing systems. Cleaning up the mess of how two things have moved forward under different incentive systems and for different purposes, that's the nasty stuff and the hard work. The accumulated disynchrony is what makes documentation suck and reduces the value of referencing it which can be a death spiral when it thereby reduces the value of producing it.

This article reminds me of the challenges of an object-oriented decomposition of a system. The solution being something like adding aspects (see AOP), relationship links with metadata, and, sure, adding a graph structure.

However, I would suggest that reducing the space between a documentation system and the code base it is documenting is one of the deeply important missing pieces. What belongs on a distilled documentation page versus in the code is the spectrum. We have data formats listed in our documentation but those should be links to the schemas (and maybe examples) in our code base.