[squeak-dev] Re: Proposal: Project Pink Book

Andreas Raab andreas.raab at gmx.de
Wed Apr 21 05:43:55 UTC 2010


Excellent ideas! I'll make a couple of assorted notes which you are 
completely free to ignore :-)

* The most helpful documentation I've used in recent years is this:
	http://www.google.com/search?q=python+tuple
	http://www.google.com/search?q=php+explode
There are actually two parts to this: 1) Indexing by Google is a must. 
The first hit on the above searches leads you directly to the right 
places. 2) The styles of the documentation is quite different. The 
Python docs provide context, giving a good overview. The php docs are 
purely reference docs but have a huge amount of user-contributed code 
snippets. Both are valuable styles of documentation.

* Try to favor something that makes it easy for people to contribute 
visibly. I.e., updating a wiki site is not a visible contribution in our 
community. I'd rather see commit comments for the documentation so that 
the community is aware of new content and who contributes it.

* Shoot for a concrete near-term achievable goal, for example: Combining 
HelpSystem with the workspace hack that I used for the release 
workspaces (i.e., just compile the text as a method) and then just allow 
people to start writing things.

I think in this phase it's more important to get a process going than to 
try to perfect the tools.

Cheers,
   - Andreas

On 4/20/2010 10:18 PM, Casey Ransberger wrote:
> Please find the attached proposal. In a workspace, do
>
> self braceFor: #theHorror.
>
> Seriously, though, I decided to go full-bore with the crazy ideas here.
> I would very much appreciate feedback of the constructively critical
> variety. If people really hate these ideas, I can go back to the drawing
> board, and come back with something folks can get behind.
>
> To be clear: I'd rather not do it all by myself, so I will be receptive
> to what you have to say about it.
>
> I am, myself, somewhat concerned that I may have erred a bit far on the
> side of tools; OTOH, I suspect that part of the reason mine was the only
> hand that went up when volunteers were called upon for the 4.0 release
> may have been: it was not a technically sexy release, and ours is a
> community of engineers. So maybe the tool ideas will go over well and
> get people engaged, I don't know.
>
> Anyway, I'm dying to hear what people think!
>
>
>
>




More information about the Squeak-dev mailing list