4 ms·

I agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree

I agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree with your point about blogposts -- publish date is like a sell-by date, makes it clear when the post has gone stale. Getting insiders to read docs is also hard. Not every piece of code is worth documenting. But I think highly critical and highly reused code is worth documenting, in part for programmers and in part so that non-coder stakeholders can understand the details of the product (i.e. 'sell what you make' if they're on the sales team).

dragonwriter 9y ago
> Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. It's not an impedance mismatch (which results from difference in the structural representations supported by different systems), it's just a content mismatch. And it's not a tooling problem, it's a process problem. Documentation is the single source of truth for intent, and development process must respect that. This becomes more and more important the more people who aren't developers need to understand the logical function of the system.