Hi Joel, I've been trying to solve similar problems for years, and eventually started a company to explore a different approach. Rather than scanning "old-school" code comments to create documentation, we built CodeStream to make it easier to capture conversation as documentation (of a sorts) right in your source code. No, it's not nearly as formal as documenting input and output parameters, but it allows you to ask questions about code and get responses much more easily, and then saves those Qs&As as comment threads tied to the codeblocks they refer to.
We wrote up the ideas behind CodeStream in our Master Plan blog post.
I'd love to hear your feedback.
We're a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.