[squeak-dev] Proposal: Project Pink Book

Michael Haupt mhaupt at gmail.com
Wed Apr 21 08:29:34 UTC 2010

Hi Casey,

that's a nice proposal, thanks. I basically agree with the ideas and
preliminary agenda - details are missing, of course, but that's fine.

First of all, please fill me in about the "pink plane" idiom. I don't
understand that. :-)

-> "Audit and improve existing class comments, and compose or procure
class comments for classes which have none"

Sure, that needs to be done - I have one concern, though. How is it
going to be packaged?

Class comment changes will have to be "released" in the form of Inbox
or Trunk uploads right now, right? I don't think this is a very good
thing. While documentation should always evolve along the code it is
intended to document, it should not be necessary to update the *code*
package when only the *documentation* changes.

In my opinion, a packageable documentation format is very important.
That also makes documentation kind of optional in an image - and
production images could be shipped (or production software installed)
without the documentation.

I know I'm touching upon some pretty hard-wired things: class comments
have, for a long time, been directly associated with classes. Can that
be decoupled somehow?

In a nutshell, it would be really cool if it was possible to work on
documentation while the code in the image rests, and just pull in
updated documentation as it becomes available.



More information about the Squeak-dev mailing list