[squeak-dev] Proposal: Project Pink Book
Bert Freudenberg
bert at freudenbergs.de
Wed Apr 21 10:35:09 UTC 2010
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 -
More information about the Squeak-dev
mailing list
|