[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
|