On 21.04.2010, at 12:27, Michael Haupt wrote:
> 
> Hi Bert,
> 
> On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg <bert at freudenbergs.de> wrote:
>> IMHO the code is exactly where the documentation belongs.
> 
> but that does not work for tutorials or anything that goes a few steps
> beyond plain class comments or single-method API-doc style
> documentation. "Documentation" is simply more than just that.

Ah, you're right. You were talking about class comments though, not tutorials.

>> But the primary documentation should be internal. External documentation should be generated from the image, not the other way around.
> 
> I agree wrt. API documentation, but I firmly believe that higher-level
> documentation is what many people would like to see. I'm extrapolating
> from my own point of view here, and anyone that don't see themselves
> represented by this are free to disagree. :-)

We don't actually disagree after all :)  It's just that the links people were excited about (Python, PHP, Ruby) were all of the API doc kind. And *that* needs to be generated from the source code IMHO.

- Bert -