[ANN] Squeak Documentation Team formation

I request the formation of the Squeak Documentation Team.

I created a document stating the plan, goals, and purpose of the
Squeak Documentation Team:
http://minnow.cc.gatech.edu/squeak/5870

I will commit to creating a useful Squeak Tutorial.

If the board finds it appropriate, I am willing to be team
leader.

Anyone want to help?

--
Matthew Fulmer

Matthew Fulmer wrote:
> I created a document stating the plan, goals, and purpose of the
> Squeak Documentation Team:
> http://minnow.cc.gatech.edu/squeak/5870

One thing I will note is that there is a difference between "teach new
Squeakers how to become excellent Squeakers" (as stated in first
paragraph) and "teach a new Squeaker how to be an excellent Morphic
programmer" (as stated under deliverables). The first one I'd expect to
be a lot about the tools whereas the latter I'd much more expect to be
about certain class libraries.

Cheers,
   - Andreas

On Thu, Sep 21, 2006 at 07:09:17PM -0700, Andreas Raab wrote:
Since Squeak is so unfamiliar to many people, I think it is not
useful to teach someone how to use the class libraries if they
do not know how to use the Squeak tools. I believe that teaching
both at once would be ideal; the interesting Morphic application
is the final outcome of the tutorial, and, in the process, one
learns how to use good squeak practices to create any
application.

That was my intent. I updated the document to reflect that. The
deliverable is now "to teach a new Squeaker how to effectively
use Squeak and to develop a Morphic application."

--
Matthew Fulmer

Andreas Raab wrote: As well as a difference between documenting and teaching  (creating a
tutorial in this case.)
Matthew: is your quest to build a team to create Squeak educational
projects - such as "Newbie-Tutorial.pr", or to create documentation?
While they overlap, their focus is quite different.

--
brad fuller

Andreas Raab wrote:
> Matthew Fulmer wrote:
>> I created a document stating the plan, goals, and purpose of the
>> Squeak Documentation Team:
>> http://minnow.cc.gatech.edu/squeak/5870
One of my goals with the Magma-Pier integration is to be able to import
data from other wiki's. I thought that I might point such an importer at
the minnow squeak wiki!

This will of course be a bit of a shakedown of the Magma-Pier combination.

However in the long run, if it prooves viable, this may provide a better
basis for refactoring and tuning minnow content.

a glimpse of the future perhaps.

Keith

               
___________________________________________________________
To help you stay safe and secure online, we've developed the all new Yahoo! Security Centre. http://uk.security.yahoo.com

On Thu, Sep 21, 2006 at 07:26:08PM -0700, Brad Fuller wrote:
Thank you for pointing that out. My intent is to create a
textual tutorial on the Swiki or elsewhere. I believe I can
handle that task. I think that a live tutorial is the focus
of the non-existent Magic Book project:
http://macos.tuwien.ac.at:9009/998031382.asHtml

My goal is to create, as quickly as possible, a very useful
textual guide to show (with text and pictures) a Squeak newbie
how to develop a useful Morphic application. As the tutorial
does that, the reader should get a feel for using the code
browsers, the object viewers, and the debugger to get the most
out of Squeak.

A live tutorial would be a good idea, but that is currently
beyond my capability. Once I write the tutorial, I should know
enough to write such an application. But not right now.

--
Matthew Fulmer

On Thu, Sep 21, 2006 at 06:47:52PM -0700, Matthew Fulmer wrote:
> I created a document stating the plan, goals, and purpose of the
> Squeak Documentation Team:
> http://minnow.cc.gatech.edu/squeak/5870

I really want to introduce beginners to (and learn myself) how
to write good unit tests, then develop a  class that conforms to
those unit tests inside the debugger. I have heard that that
capability is one of the best things about Smalltalk, and I know
that unit tests are a *very* good thing to use.

Should I expose a Squeak beginner to this topic early on?
or should that be the topic of a separate tutorial?

I do not know if my tutorial will target novice programmers or
not.

--
Matthew Fulmer

Am 21.09.2006 um 21:47 schrieb Matthew Fulmer:

> I request the formation of the Squeak Documentation Team.
>
> If the board finds it appropriate, I am willing to be team
> leader.

Great!

- Bert -

Le Sep 21, 2006, à 8:25 PM, Matthew Fulmer a écrit :

I like what you mentioned in an earlier email about building an
application as a framework for a tutorial. And I think that doing
test-first development is wonderful. Even if its just a couple simple
tests on the model for the gui (assuming you choose to put a gui on it)

>
> I do not know if my tutorial will target novice programmers or
> not.
>

I would target novice programmers. Why not start there with a really
well-done intro tutorial that's up to date with the latest squeak dev
image and can be easily kept up to date?

> --
> Matthew Fulmer
>

On Thu, Sep 21, 2006 at 09:45:53PM -0700, Eric Winger wrote:
I am not sure what email you are referring to. Are you saying
that you think it is a good idea to walk the reader through the
development of a real application? If so, I assumed that this is
the only way to structure the tutorial.  Do you have a different
idea?

This paragraph is difficult to understand; could you restate it?

> >I do not know if my tutorial will target novice programmers or
> >not.
> >
>
> I would target novice programmers. Why not start there with a really
> well-done intro tutorial that's up to date with the latest squeak dev
> image and can be easily kept up to date?

That is an interesting idea; I would write a tutorial for
non-programmers completely differently than one for a
programmer.

For a programmer, I would walk them through the environment,
then have them write a transcript-based program along the lines
of "Hello world", but a bit more functional. Then I would show
them how to build a window (I am assuming it is similar to Java
Swing or GTK) and make it display useful information.

I am unsure how I could incorporate test-driven programming into
that, as that is a *very* jarring concept to me, and hence to an
average programmer.


To target a non-programmer, I would take a completely different
approach: I would first show them how to put a widget into the
playfield, then how to manipulate it. I may or may not introduce
eToys to the reader. I would never show them the Transcript; it
seems useless when compared to Squeak's other debugging tools. I
would then show them the ifTrue:ifFalse: and do: methods. I may
introduce classes and inheritance; probably not. I am not sure
how I would introduce them to windows and layouts.  Trying to
think like a non-programmer is making my brain hurt :(

I don't see why I could not introduce test-driven programming to
a non-programmer at her inception; it is the way normal people
tend to think about problems. Normal people define a situation
(test case) and then define how the object should behave in that
situation.  Programmers are backwards: they tend to define what
the object can do, then warp the situation to fit the object.


I guess I need to choose which of three tutorials to write:

1. Programmer-targeted without test-driven programming (short)
    This is the easiest of the tutorials to write, and may be
    the one most in demand. Since I am in the same situation as
    my audience, this would probably be the most realistic
    tutorial.

2. Programmer-targeted with test-driven programming (medium)
    This may be difficult to write, since it may be very
    disorienting tutorial to the reader.

3. non-programmer targeted (long)
    This would be the most interesting to write, and will be the
    longest of the three choices. Writing this tutorial would be
    a very direct measure of Squeak's ease of use: the length of
    this tutorial should be inversely proportional to how
    comprehensible Squeak is to normal folk. (a zero length
    tutorial would be a perfect score by this metric)

Which would be the most useful? Do we need to make more than one
tutorial? Please comment.

--
Matthew Fulmer

Hi Matthew and all!

First of all - great initiative! I will try my hardest to support and
help as time permits. And it is really good that you make this effort
"official" through the Team model - it gives it all much more "weight"
and makes sure that we slightly disillusioned oldtimers actually open
our eyes. ;)

Matthew Fulmer <[hidden email]> wrote:
> > Matthew: is your quest to build a team to create Squeak educational
> > projects - such as "Newbie-Tutorial.pr", or to create documentation?
> > While they overlap, their focus is quite different.
>
> Thank you for pointing that out. My intent is to create a
> textual tutorial on the Swiki or elsewhere. I believe I can
> handle that task.

And I think this is "smart". As Bryce said on the chat - a tutorial is
probably what gives most "bang for the buck". (well, he said something
similar)

As you note in your plan, two side effects of this project are:
        - Indexing resources we already have. Can't be wrong, even though the
index eventually probably will turn unmaintained (devil speaking from
experience) ;)
        - Add/improve existing class comments as the team members learn about
stuff. This is IMHO the best aspect of your plan!

If this team, while writing the tutorial, produces class comments that
are non existent or bad today - then that will be a REAL tangible
result. And they will enter the image and thus be *somewhat* protected
from getting lost and unmaintained.

Now, let me ask a really annoying question: What will happen with this
tutorial after year 2008?

If the answer is - "dunno" - then that is perfectly fine of course. I
just want people to realize that many tutorials have in fact been
written over the years and AFAIK *ALL* have turned stale. Feel free to
point me to an up-to-date maintained Morphic tutorial and prove me
wrong. :) So some kind of planned antidote for that grim future would be
nice to have - whatever that would be.

> I think that a live tutorial is the focus
> of the non-existent Magic Book project:
> http://macos.tuwien.ac.at:9009/998031382.asHtml

Actually, that is not the focus of the Magic Book - at least not as I
have imagined it :).
If you read that posting carefully (and I think it is worth reading) it
says:

        "The actual book would imho best be written as a Morphic tool with the
        ability to have the actual chapter contents loaded on demand in
multiple
        formats - HTML, wiki text, Morphic code, Morphic projects, whatever.
And
        each chapter could be a separate package on SM having separate
        maintainers etc. It could spawn an external browser for HTML chapters,
        it could show Morphic content directly, it could spawn an external
        browser for wiki contents etc, etc."

This means that the Magic Book itself is just a regular Morphic tool and
that the content can be of many kinds - the simplest being plain old
ugly text (and not at all a live tutorial). Darn, I am really itching to
write that tool... :)

regards, Göran

On 9/21/06, Matthew Fulmer <[hidden email]> wrote:
>
> I really want to introduce beginners to (and learn myself) how
> to write good unit tests, then develop a  class that conforms to
> those unit tests inside the debugger. I have heard that that
> capability is one of the best things about Smalltalk, and I know
> that unit tests are a *very* good thing to use.
>
> Should I expose a Squeak beginner to this topic early on?
> or should that be the topic of a separate tutorial?

>From the beginning.

One of the key ideas in programming is the difference betwen an abstraction
and its implementation, between the "outside" and the "inside" of an object.
An object has an interface and it has an implementation, even in Smalltalk.
Ideally, if you want to use an object, you can just learn its
interface and you don't
have to learn its implementation, though the ideal is rarely met.  But
to think about
a large system, you have to focus your mind on a small part and ignore
the details
of the rest.  And then you switch to another small part, and another,
and another.
Sometimes the "small part" is the architecture, so it encompasses the
entire system,
but you still have to focus on one part of the system and ignore the
rest, because
of the limitations of the human brain.

Unit tests are a very good way to think about the outside of an
object.  They aren't
the only way.  Little scripts in a workspace, example applications
that use the object,
and "all senders" are other ways.  But unit tests are a very good way
and should be
emphasized from the beginning.

However, do not say "first write tests, then write a class".  This is
as wrong as "first
write class, then write tests".  The inside and the outside view of an
obect are both
essential.  You can't get a good class unless you think of them both.
So, you will
first start with a simple inside and outside view, then you'll
gradually make it more
sophisticated.    This means you will write your tests and the methods
together.
Perhaps you'll first write a test, then a method, or perhaps you'll
write a few methods
and then a few tests.  What is important is that you think of them together.

Not all classes have unit tests.  If you develop a class by
refactoring your code,
such as by generalizing a couple of concrete classes to factor out a
common superclass,
or by converting a case statement into polymorphism and splitting out
some strategies,
then the original code will have tests and they will execute the new
class as a side
effect.  The application that uses the new class shows its outside
view.   A quality
assurance expert would probably want to write some new tests for the new class,
but a designer probably would not.  That is because the designer is
mostly interested
in the tests to help define the outside view of an object, and the
tests aren't needed for
that.  I don't think you should try to teach the QA point of view of
testing in an introductary
programming course, but you should definitely teach the designers
point of view of testing.

-Ralph Johnson

Count me in when you have specific tasks to launch. At the moment I need to focus on learning enough so I can put fingers-to-keyboard and start producing code as quickly as possible.

I irc'ed this comment yesterday and reproduce here in case you missed it:

>>>
<matmo> tapple: nice to see you kick off the "Swiki Cleanup". I have some ideas that I will put forward sometime soon after I complete my large-ish reading list! But for now I have one main suggestion which is a "Beginners Walk-Through" page. This would contain links to existing pages in the order that the beginner would follow to get off the ground. I know there are already page(s) aiming to do this but a more focused one would be welcome. Ultimately I would like to see a complete training package *in* Squeak - why not if Squeak is live up to its intented purpose and considering a large part of the dev effort has an educational bias?
<<<

Later I came across this which is one of the most concise introductions I have seen so far (at least if you some programming experience): http://wilkesjoiner.com/UsingSqueak.html. Best part for me is the monticello introduction because I naturally wondered "ok, if I start writing my own classes where the hell do I store and manage them long term?". I was also confused to begin with as to why Squeak seemingly had two package managers.

While I'm giving a "newby" perspective I would like to add that even though the concept of "applications" may be scorned upon in the Squeak/Smalltalk/OO world, that to the beginner (albiet conditioned by current GUI/ main-stream os standards) the absence of clear "mother" objects (ie, those that would serve the role of "application" ("mother" being my terminology, I claim it but you are free to quote with suitable reference (joke))) is VERY confusing and frustrating! I cannot imagine why a programmer would create something and then not make it *crystal clear* how to use it by providing at least one concrete example that assumes little/no prior knowledge of the target domain. I have seen two suggestions as a sort-of excuse for this situation 1) Use the test classes/methods 2) Squeakers/Smalltalkers rely heavily on reading the code. Both were welcome suggestions and may be valid *once* you are familiar with the Squeak/Smalltalk environment. Chicken&Egg, need I say more? Well may be an example so you don't boo me for not providing a specific example ;-) I have failed at several attempts to open a flash player "application" (tounge-in-cheek), having tried left-click menu, code, morphs and anything else I came across. I suspect I nearly got there on one attempt only to discover the url I used pointed to a .swf that was not supported in v3 flash player/component, hmmmm.

Phew! Long paragraph! So in summary: consider the paradigm shift new users, even those with programming experience, may be experiencing and provide a smooth transition to a *much better* paradigm, be it in text, in the form of a tools, convention or even beginner-style menus.

I have three other points to make which, while possibly not directly related to Matthews objective, may be worth pondering:

1) When I started trawling the web for Squeak/Smalltalk info I was amazed at how much there is and the long history that goes with the topic/s. In fact there is so much I am now drowning in it! So I am dazed that despite having a keen interest, a couple of related degrees and a career in computers/programming spanning 20+ years I seem to have had a *complete* blindspot when it comes to Smalltalk. For sure I have seen references to it for years and possibly even read a few paragraphs here and there, I am familiar with OO concepts from age ~13 (ok, I am 42 if you really have to know), I have programmed in a variety of languages on a variety of platforms but despite all this and the heritage of smalltalk we have never really met until last week. Maybe it is me, maybe it was my reaction to C++ ("you call this progress!?") but I don't think so. Considering if I had never had an interest in Ruby I probably would never had "discovered" Squeak/Smalltalk, I googled for "programming +ruby" and "programming +smalltalk": 18,800,000 hits for the former compared to 6,270,000 for the latter... there's something wrong here. Discuss. (sorry for the ending, just had to, lol)

2) Wow such vision! Fantastic concept/s! Such history! It just *must* have a fantastic future, doesn't it? Amazed as I am, especially with Squeak, I quickly started to wonder if I had missed the boat, so much so that the boat is actually on its return journey. Sorry to be obtuse, I have no intention to offend... but (having prepared you, my dear reader, lol), what has gone wrong? Where is the all-singing all-dancing experience promised by Squeak? Oh I see, it's only on offer if you are aged 16 or less (maybe much much less). Damn kids, why should they have all the fun, with their etoys and what-not? I jest but there is a serious point: all those aspects that are (very honourably) put to good use in education should be pushed up-stream. I mean this literally, to the older generation. I don't know the population demographics in other countries but I suspect that similar to the UK the population as a whole is growing older. Here in the UK the biggest group of voters is set to be the over 60's. Why not upgrade Squeak/EToys and retarget at this group who I firmly believe would welcome a better computing experience? Next door to me are a couple in their 70's. Less than a year ago they got broadband. I set things up for them, showed them how to start some card games and use a web browser... but that's about it. I quickly realised to go much further would make the experience unpleasent because of all the many new things I would have to expose them to. The irony is they are connected but very much still disconnected in terms of what the internet can offer them (advice, discussions, even sharing photo's with their grandchildren!). Imagine what a repackaged Squeak/Squeakland could offer them if it truly offered a safe multimedia environment, transparently connecting them to friends&family and their social groups? No web browser issues/insecurities, no protocols to learn talk to others, drag&drop to distribute their photo's, maybe personal help at a click of button, auto-updated, etc, all within a single environment based on Squeak? Imagine. (yeah, yeah, "talk is cheap" you say and I say "thinking is even cheaper, have you counted the calories?" - don't know why I added that but I did and now there's nothing I can do about it, shrug)
 
3) This is maybe the least related to the OP, so sorry, but I got to wonder about all those young SqueakLanders, some of which must surely be young adults by now. Was the experience so successful that some even started to investigate Squeak itself further? Did any become Smalltalk programmers? Did the programme produce any potential "BIG THINKERS"? Will we see a massive growth in Squeak/Smalltalk interest as these enlightened individuals spread the message? If not, why not? PS: these are just idle thoughts and if the programme simply(?) achieved Alan Kays (et al) objectives then that, obviously, is enough of an answer for me.

Thank you, very much, for having the patience and personal fortitude for reading this far. I'm sure I wouldn't - lol.

Le Sep 21, 2006, à 11:09 PM, Matthew Fulmer a écrit :

>> <snip>



Nope. That's it.
>
> This paragraph is difficult to understand; could you restate it?

Unit tests are a great idea! (hope that's more clear, one should never
write emails when they're tired) :)

I was referring to novice squeakers (newbs). I should have been more
clear.

I'm not sure that writing a tutorial for a non-programmer is worth the
effort, at least for now
I would stick with writing a tutorial for a "novice squeak programmer"
first.
ie - someone who can barely open an image, but may be (or may not be)
quite proficient in another language.

I'm in favor of putting unit tests in the first tutorial. I don't think
its that hard to do with a simple application and it shows benefit. For
example, let's say the tutorial has this in it.

* Write a test to show what "foo" behavior should do.
*run the test, it fails.
* Write the method "foo"
* run the test, it passes! Yay!
* Now realize that foo is wrong and you have to change it.
* rewrite method "foo" to do the write thing
* run the test, it breaks.

This can immediately show the value of test driven development.

And I don't think that it's unreasonable to put that in the beginners
tutorial.


>
> 2. Programmer-targeted with test-driven programming (medium)
>     This may be difficult to write, since it may be very
>     disorienting tutorial to the reader.



>
> 3. non-programmer targeted (long)
>     This would be the most interesting to write, and will be the
>     longest of the three choices. Writing this tutorial would be
>     a very direct measure of Squeak's ease of use: the length of
>     this tutorial should be inversely proportional to how
>     comprehensible Squeak is to normal folk. (a zero length
>     tutorial would be a perfect score by this metric)

Like I said, I think #3 should wait. The other is of more immediate
value.

>
> Which would be the most useful? Do we need to make more than one
> tutorial? Please comment.
>
> --
> Matthew Fulmer
>

Mathew,

I'll throw my hat in the ring. I am a newbie and my contributions will
have to follow my learning curve.

I'd also add debugging as a topic to the scope. How about 4 sections.

1. Topics relating to the environment and tools.(installation,
browsing, coding, debugging, monticello)
2. Topics related to Smalltalk core classes (just the language)
3. Topcis related to extended classes (gui, mvc, morphic etc)
4. Topics related to application classes (seaside etc)

I think the tutorial section should cover all topics which would make
one a proficient smalltaker. I am learning all the stuff bit by bit
hunting and pecking here and there.

-bakki

On 9/21/06, Matthew Fulmer <[hidden email]> wrote:

Matthew,

I think tdd should be included but we should start with the two great
resources on the subject so we don't reinvent the wheel.

Kent Becks tutorial at:
http://www.xprogramming.com/testfram.htm

and Stef's article at:
http://scgwiki.iam.unibe.ch:8080/ST2002/uploads/1/SUnit-V1.pdf

THese can be extended with some kind of a mini app (like the Java Pet
store? which could be a common thread for all topics.

-bakki

On 9/21/06, Matthew Fulmer <[hidden email]> wrote:

Go Keith! +1

On 22-Sep-06, at 9:37 AM, Bakki Kudva wrote:

> Mathew,
>
> I'll throw my hat in the ring. I am a newbie and my contributions will
> have to follow my learning curve.

This is a good thing; contributions from newcomers explaining where  
they find problems and faults are extremely valuable. *please* record  
all the problems you stumble over; it is in the nature of humans to  
very quickly learn to avoid problems with tools and if you don't  
record them you will forget they even exist. Those of us with long  
histories of using Smalltalk and Squeak are almost useless in that  
respect. We know so much about what not to do....

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Oxymorons: Found missing

On Fri, Sep 22, 2006 at 12:37:30PM -0400, Bakki Kudva wrote:
> Mathew,
>
> I'll throw my hat in the ring. I am a newbie and my contributions will
> have to follow my learning curve.

Thank you much. Could you add your name to
http://minnow.cc.gatech.edu/squeak/5870

Ask on #squeak for the user name and password

> I'd also add debugging as a topic to the scope. How about 4 sections.
>
> 1. Topics relating to the environment and tools.(installation,
> browsing, coding, debugging, monticello)
> 2. Topics related to Smalltalk core classes (just the language)
> 3. Topcis related to extended classes (gui, mvc, morphic etc)
> 4. Topics related to application classes (seaside etc)

That is nearly the same outline I had in mind:

1. Installation, browsing
2. Language, coding, core classes
3. Collections. Here I would have the reader build a simple,
    Transcript-based program. Unit tests may be here.
4. Morphic. This would include:
    4.1. Basic widgets: buttons, hyperlinks, text, lists
    4.2. Creating and populating a SystemWindow
    4.3. Assembling a useful application.

> I think the tutorial section should cover all topics which would make
> one a proficient smalltaker. I am learning all the stuff bit by bit
> hunting and pecking here and there.

I agree; however, what topics this includes is debatable.

Here is my current criteria, and how I would rank relevant topics:
Is this skill essential to being a good Squeak and Morphic Programmer?

Yes:
    Installation
    Debugging
    Browsing
    Coding
    Smalltalk Language
    Collections
    Morphic

Probably:
    Unit Testing
    Change Sets

Maybe:
    SqueakSource
    SqueakMap
    MontiCello
    Projects

Probably not:
    seaside

No:
    mvc

There are three options for each topic:
1. Include it in this beginners tutorial, because that skill is
    essential to being a good Squeak programmer.
2. Create another tutorial to address it.
3. Link to an existing tutorial of the appropriate scope.

I do not want to duplicate effort; I want to create a tutorial
to take a programmer from "Squeak? Huh?" to "I know how to use
squeak to develop useful applications, and I know where to go
for help"

The content and organization of the tutorial is an open topic.

--
Matthew Fulmer

On 9/22/06, Matthew Fulmer <[hidden email]> wrote:
> Thank you much. Could you add your name to
> http://minnow.cc.gatech.edu/squeak/5870

I will.

> Ask on #squeak for the user name and password

I would move both of these to yes. I am not sure of unless you are
doing desktop apps. I think it falls in the application domain. Some
one correct me if I am wrong. eg. If you are doing only web apps
(Seaside, Magritte, Pier etc) you don't need to know much of Morphic
and vice versa.

>
> Maybe:
>     SqueakSource
>     SqueakMap
>     MontiCello
>     Projects

I consider MOnticello, SqueakMap and then SqueakSource as essential
developer skills as well.

> Probably not:
>     seaside

This would be a section 4 topic.

I'd like to re-iterate about the classes reference (a la php). It
could stand on its own.

-bakki