Smalltalk › Squeak › Squeak - Dev

Proposal: Project Pink Book

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

45 messages Options

123

Casey Ransberger-2

Proposal: Project Pink Book

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!

Project Proposal.pdf (5K) Download Attachment

Andreas.Raab

Re: Proposal: Project Pink Book

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

Hans-Martin Mosner

Re: Proposal: Project Pink Book

In reply to this post by Casey Ransberger-2

Am 21.04.2010 07:18, schrieb Casey Ransberger:
> Anyway, I'm dying to hear what people think!
Nothing to die for...

The PDF comes up completely blank with the Ubuntu PDF displayer
(evince). Looks like evince isn't able to handle the embedded type1
font, strange. As always with attached documents in mail, please
consider twice whether what you want to say can't be said in simple
words within an e-mail. I realize that sending PDFs is much friendlier
than using some document format invented by you-know-who.

I could select the invisible text and copy it into a workspace, so the
textual contents were readable.
Overall, I think the direction sounds nice, but I can't say whether it
will work - that depends on getting a critical mass of Squeakers into
the boat.

Cheers,
Hans-Martin

Casey Ransberger-2

Re: Proposal: Project Pink Book

In reply to this post by Andreas.Raab

On Tue, Apr 20, 2010 at 10:43 PM, Andreas Raab <[hidden email]> 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!

Andreas.Raab

Re: Proposal: Project Pink Book

On 4/20/2010 11:23 PM, Casey Ransberger wrote:

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

Try this too: Load HelpSystem, file in the attached code. Then edit your
help pages simply via:

HelpOnHelp edit: #introduction.

This uses the trick that I mentioned above. You can edit text just like
you usually would with all Squeaky goodness like emphasis, doIts,
printIts etc. When done, simply accept and the method gets compiled.
Extra bonus: Changing the window label also changes the topic title :-)

Cheers,
- Andreas

CustomHelpEditing.st (1K) Download Attachment

Tobias Pape

Re: Proposal: Project Pink Book

In reply to this post by Andreas.Raab

Seeing this, i was reminded of
http://soek.goodies.st/

So Long,
-Tobias

Am 2010-04-21 um 07:43 schrieb Andreas Raab:

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

Casey Ransberger-2

Re: Proposal: Project Pink Book

That's pretty darned nice. Do you happen to know what the stack looks like there? Is it Squeak? Pharo? VW? I'm going to try to figure out who's site that is and make contact in the next couple of days.

On Wed, Apr 21, 2010 at 12:20 AM, Tobias Pape <[hidden email]> wrote:

Seeing this, i was reminded of
http://soek.goodies.st/

So Long,
-Tobias

Am 2010-04-21 um 07:43 schrieb Andreas Raab:

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

Andreas.Raab

Re: Proposal: Project Pink Book

On 4/21/2010 12:38 AM, Casey Ransberger wrote:
> That's pretty darned nice. Do you happen to know what the stack looks
> like there? Is it Squeak? Pharo? VW? I'm going to try to figure out
> who's site that is and make contact in the next couple of days.

http://philemonworks.wordpress.com/2009/11/13/soek-goodies-st-exploring-open-source-smalltalk-libraries/

Tags: s3, seaside, Smalltalk, soek, WebVelocity

Michael Haupt-3

Re: Proposal: Project Pink Book

In reply to this post by Casey Ransberger-2

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.

Best,

Michael

Stéphane Rollandin

Re: Proposal: Project Pink Book

In reply to this post by Casey Ransberger-2

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

As for embedded documentation, I would recommend to check Emacs
(featuring tutorial, books, info pages, introspection and function doc
strings all integrated together) and Factor (amazing browsers)

http://docs.factorcode.org/

Stef

Casey Ransberger-2

Re: Proposal: Project Pink Book

Oh cool. Yes the Factor pages are hot. It's totally interactive, I love it. And yes, I use Emacs when I'm not using Squeak:)

On Apr 21, 2010, at 1:32 AM, Stéphane Rollandin <[hidden email]> wrote:

>> * 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/
>
> As for embedded documentation, I would recommend to check Emacs (featuring tutorial, books, info pages, introspection and function doc strings all integrated together) and Factor (amazing browsers)
>
> http://docs.factorcode.org/
>
>
> Stef
>
>
>
>

Hannes Hirzel

Re: Proposal: Project Pink Book

In reply to this post by Michael Haupt-3

On 4/21/10, Michael Haupt <[hidden email]> wrote:
> 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. :-)

Yes, "pink plane" has a special meaning. I assume Casey want's to allude to it.

However for the time being why not just talk about 'HelpSystem'.

Personally I would like to see a focus on short term attainable goals.

Hannes

Bert Freudenberg

Re: Proposal: Project Pink Book

In reply to this post by Michael Haupt-3

On 21.04.2010, at 10:29, Michael Haupt wrote:
>
> 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.

IMHO the code is exactly where the documentation belongs. Sure, make external editors and even formats or databases or whatever if that is more convenient. But the authoritative version should be the one in the image. It's not official unless committed.

> 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 agree that the documentation should be removable from the image. But in production you wouldn't ship the sources anyway. Comments are only in the source files, not the image. And if methods are used to store documentation literally, those could be removed when deploying.

But the primary documentation should be internal. External documentation should be generated from the image, not the other way around.

- Bert -

Michael Haupt-3

Re: Proposal: Project Pink Book

Hi Bert,

On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg <[hidden email]> 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.

> 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. :-)

Best,

Michael

Bert Freudenberg

Pink plane vs blue plane (was Re: Proposal: Project Pink Book)

In reply to this post by Michael Haupt-3

On 21.04.2010, at 10:29, Michael Haupt wrote:
>
> First of all, please fill me in about the "pink plane" idiom. I don't
> understand that. :-)

It's an Alanism. Look at VPRI's logo :)

Dan Ingalls applied the planes idea to Squeak:

=======================
There are two strong, often opposed forces at work in the Squeak team. But, we have managed to keep it together long enough that it's probably adequate to articulate the two and you can guess at where equilibrium will take us. These were most recently articulated in Alan's allusion to Koestler's metaphor of progress in two orthogonal planes: a horizontal pink plane of incremental improvement, and a vertical blue plane of paradigm shift. The colors are Alan's.

Pink plane forces involve making an ever-better Smalltalk-80 system that can serve a wide range of research and academic needs, while leveraging off the large body of ST-80 documentation, existing code archives, and synergy with high-performance commercial ST-80 systems. In this plane, Squeak's high level of compatibility with the ST-80 language (and even with the MVCdisplay architecture) is a plus, and current progress forces are aimed at a higher performing interpreter, with support for block closures, exception handling, as well as some answer to various needs for finalization. [...]

Blue plane forces involve a very different graphics model, evolution of the language model, and hopefully an even simpler, yet more powerful language kernel. Each of these constitutes significant change, and is thus at odds with various entrenched interests. At the same time, each offers significant benefits.
=======================

Read the full thing: http://wiki.squeak.org/squeak/158

To Alan himself, the two planes are way more profound:
http://www.memestreams.net/users/akira/blogid4041444/

- Bert -

Bert Freudenberg

Re: Proposal: Project Pink Book

In reply to this post by Michael Haupt-3

On 21.04.2010, at 12:27, Michael Haupt wrote:
>
> Hi Bert,
>
> On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg <[hidden email]> 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 -

Michael Haupt-3

Re: Pink plane vs blue plane (was Re: Proposal: Project Pink Book)

In reply to this post by Bert Freudenberg

Hi Bert,

thanks. The Koestler reference made everything clear and
understandable. The colour metaphor was really unfamiliar. :-)

Best,

Michael

Michael Haupt-3

Re: Proposal: Project Pink Book

In reply to this post by Bert Freudenberg

Hi Bert,

On Wed, Apr 21, 2010 at 12:35 PM, Bert Freudenberg <[hidden email]> wrote:
> Ah, you're right. You were talking about class comments though, not tutorials.

when I talk about documentation, it envolves all flavours. :-)

The start were class comments; correct. But I was thinking a bit
ahead. Sorry for not making that more clear.

Best,

Michael

Rita Freudenberg

Re: Pink plane vs blue plane (was Re: Proposal: Project Pink Book)

In reply to this post by Bert Freudenberg

On Apr 21, 2010, at 12:30 PM, Bert Freudenberg wrote:

>
>
> Read the full thing: http://wiki.squeak.org/squeak/158
>
> To Alan himself, the two planes are way more profound:
> http://www.memestreams.net/users/akira/blogid4041444/

In this article, there is a non-working link to swiki.squeakland.org. Do you know what used to be on that server?

Rita
>
> - Bert -
>
>
>
>

CdAB63

Re: Proposal: Project Pink Book

In reply to this post by Casey Ransberger-2

Great excellent ideas & a very sensible proposal.

I'll support such initiative.

Regards,

CdAB

signature.asc (269 bytes) Download Attachment

123