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

Casey Ransberger casey.obrien.r at gmail.com
Wed Apr 21 06:23:37 UTC 2010


On Tue, Apr 20, 2010 at 10:43 PM, Andreas Raab <andreas.raab at gmx.de> wrote:

> 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


Good stuff. I really like the feel of the Python version. They have great
documentation in general. While we're looking at other web-based
documentation frameworks, you must check out:

http://www.ruby-doc.org/core/

 - Note the influence of the ST-80 class browser.

 - Scroll the middle pane, choose Array, click on the title of a method, and
note that the implementation (probably in C) pops up in a new window. This
is utterly primitive compared to what we can do, and still kind of cool.

 Indexing by Google is a must.


Yes. For a time my whole life was about being indexed by Google, when I was
at WhitePages. I know this all too well.


> * 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.


100% agreement. There are actually a number of reasons why it would be neat
to harvest documentation with Monticello. Above all, it lets us keep linkage
between documentation and the code that it describes. It also gets
versioned. Maybe merging will prove useful. Visibility is also way cool. As
I mentioned in my reply to Michael, we can also have e.g., an option to
toggle between stable and nightly API docs right in the web browser, and use
MC to pull docs straight to the server.


>

* 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.
>

Totally; what's funny is, I wasn't aware of HelpSystem until today (I seem
to have missed the previous thread about it) and was expecting to have to
build that part myself. My plan was to just send things #storeString and
stick them in methods, and see how far that took me. I will dig through my
files to revisit the workspace hack.

As I write this I've sent #storeString to a HelpTopic automatically
generated from Integer and it looks as though it worked and performed
acceptably. My gut say this is going to work.


> 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!
>>
>>
>>
>>
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100420/209a890e/attachment.htm


More information about the Squeak-dev mailing list