As someone with a stake in lots of this stuff, this interview is interesting to listen to. I especially appreciated the bit about 3/4 of the way through about how doing Docco affected Pow. To quote:
"Pow started out without any documentation. I went through and added the Docco stuff later.
"I thought it was fascinating the way it actually changed the code. As I would go through and document things, I would run in to cases where they were too hard to explain. Something was too hard to explain or looked too awkward. So I'd refactor it to be more linear, more narrative -- and it matched up with the documentation, and seemed so much nicer.
"I think that's half the benefit of Docco, and the other half is that it makes it so much easier for anyone to come in to the project and understand what's going on and contribute a change."
I can attest to that, both from reading and writing code with Docco documentation.
It's also great IMHO for getting an uncluttered view of code. In many cases, no matter how well written, the documentation is not enough. And while Docco is all about documentation, it shines even then.
Comments
As someone with a stake in lots of this stuff, this interview is interesting to listen to. I especially appreciated the bit about 3/4 of the way through about how doing Docco affected Pow. To quote:
"Pow started out without any documentation. I went through and added the Docco stuff later.
"I thought it was fascinating the way it actually changed the code. As I would go through and document things, I would run in to cases where they were too hard to explain. Something was too hard to explain or looked too awkward. So I'd refactor it to be more linear, more narrative -- and it matched up with the documentation, and seemed so much nicer.
"I think that's half the benefit of Docco, and the other half is that it makes it so much easier for anyone to come in to the project and understand what's going on and contribute a change."
I can attest to that, both from reading and writing code with Docco documentation.
It's also great IMHO for getting an uncluttered view of code. In many cases, no matter how well written, the documentation is not enough. And while Docco is all about documentation, it shines even then.