[jashkenas]

I hear you, but I'm concerned about trampling on other folks' code without being involved in a long term relationship. Code bombs dropped by consultants often have this sort of problem -- where some of the more invasive changes either aren't welcome or are more difficult to integrate with the existing system than they're worth. I'm hoping that having inline examples of working code, with references to the source, strikes a happy medium here. Plus, "teach a man to fish", and all.

That said, we do live in a Git world these days. Maybe a fancier package could include the creation of a branch that implements some of the tweaks/changes/ideas.

[drsim]

A combo of doc + a branch commit would be spot on.

You're right on the code bomb problem, but I think a good review involves making a judgement on the entire codebase. Something may be the 'right' thing to do but completely uneconomical due to dependencies.

Understanding the impact of a recommendation leads to a valuable refactor or rewrite call that developers often have to make on a mature ecosystem.