[ANN] Squeak Documentation Team formation

>From: Matthew Fulmer <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: [hidden email]
>Subject: [ANN] Squeak Documentation Team formation
>Date: Thu, 21 Sep 2006 18:47:52 -0700
>
>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
>

>From: Matthew Fulmer <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: [hidden email]
>Subject: Should Test-Driven Development be in the beginners tutorial?
>Date: Thu, 21 Sep 2006 20:25:17 -0700
>
>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
>

>From: [hidden email]
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: The general-purpose Squeak developers
>list<[hidden email]>
>Subject: Re: [ANN] Squeak Documentation Team formation
>Date: Fri, 22 Sep 2006 08:51:29 +0200
>
>Now, let me ask a really annoying question: What will happen with this
>tutorial after year 2008?
>

>From: "Ralph Johnson" <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: "The general-purpose Squeak developers
>list"<[hidden email]>
>Subject: Re: Should Test-Driven Development be in the beginners tutorial?
>Date: Sat, 23 Sep 2006 10:00:01 -0500
>
>>A possible way is to make a theme like they did in Dolphin.  In Dolphin
>>the
>>tutorial is about making a minimal bank account program.  Someone wrote
>>tutorials about how to extend these later.  I think that could work.  You
>>make your simple Morhpic app, then in the next installment you explain the
>>features your application doesn't have but needs and so you explain that
>>you
>>want to first make unit tests to ensure you don't break anything.
>
>Matthew asked about unit tests, but he really should have asked about
>test-first.
>
>This isn't test-first.  Unit tests have many purposes.  Only one is to
>ensure that changes don't break anything.  A more important purpose is
>to ensure that you know what you are programming.  Test-first lets you
>think about the interface to your classes from the users point of
>view.  It provides documenation to how to use your classes, and
>provides a kind of specification.  Test-first is about design even
>more than testing.
>
>-Ralph Johnson
>

> On Fri, Sep 22, 2006 at 01:39:43PM -0700, Craig Latta wrote:
>  
>>      The board approves the team and you as its leader. I'm the default
>> teams liaison; if you need any help from us, please let me know.
>>    
>
> Who do I refer volunteers to for wiki edit permissions? Several
> people have good ideas and are willing to contribute, but I do
> not know of a reliable way to give them wiki edit permissions.
>
> Do I have permission to distribute the Swiki password to those
> who want to help?

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

> 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

> 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

>
> Well, that is valid.  The alternative to what I said is:  if your going to
> train someone, train them right from the start.
>
> I guess I don't do it the way you described because I make my classes with
> an interface, then part way through I determine my first cut was wrong.  If
> I started with the tests I would have to change all the tests along with my
> class changes (right?), effectively doubling the work I do now.
>
> Has any work been done to integrate testing into the browser?  It seems like
> some of the things you would write tests for are pretty predictable and
> could be automated or semi-automated.
>
> >From: "Ralph Johnson" <[hidden email]>
> >Reply-To: The general-purpose Squeak developers
> >list<[hidden email]>
> >To: "The general-purpose Squeak developers
> >list"<[hidden email]>
> >Subject: Re: Should Test-Driven Development be in the beginners tutorial?
> >Date: Sat, 23 Sep 2006 10:00:01 -0500
> >
> >>A possible way is to make a theme like they did in Dolphin.  In Dolphin
> >>the
> >>tutorial is about making a minimal bank account program.  Someone wrote
> >>tutorials about how to extend these later.  I think that could work.  You
> >>make your simple Morhpic app, then in the next installment you explain the
> >>features your application doesn't have but needs and so you explain that
> >>you
> >>want to first make unit tests to ensure you don't break anything.
> >
> >Matthew asked about unit tests, but he really should have asked about
> >test-first.
> >
> >This isn't test-first.  Unit tests have many purposes.  Only one is to
> >ensure that changes don't break anything.  A more important purpose is
> >to ensure that you know what you are programming.  Test-first lets you
> >think about the interface to your classes from the users point of
> >view.  It provides documenation to how to use your classes, and
> >provides a kind of specification.  Test-first is about design even
> >more than testing.
> >
> >-Ralph Johnson
> >
>
>
>
>

> Cincom has a pair of tutorials that are excellent.  They are intended for
> people with little programming and no smalltalk experience.  They contain
> lots of graphics and lots of links to more detailed information.  You are
> guided through developing an application that analyzes web log stats by
> first coding in a workspace and and then moving your code to methods.  The
> first tutorial creates the classes and methods.  In the second you develop
> a gui for the application and package it.  Along the way you learn the
> basics of using smalltalk.  By the end you hunger for more.
>
> While I'm sure you have your own ideas of content, you would do well to
> look over their material:
>
> http://www.cincomsmalltalk.com/userblogs/cincom/blogView?content=tutorials

> On Sun, Sep 24, 2006 at 10:41:23AM -0400, Chris Kassopulo wrote:
> > Cincom has a pair of tutorials that are excellent.  They are intended for
> > people with little programming and no smalltalk experience.  They contain
> > lots of graphics and lots of links to more detailed information.  You are
> > guided through developing an application that analyzes web log stats by
> > first coding in a workspace and and then moving your code to methods.  The
> > first tutorial creates the classes and methods.  In the second you develop
> > a gui for the application and package it.  Along the way you learn the
> > basics of using smalltalk.  By the end you hunger for more.
> >
> > While I'm sure you have your own ideas of content, you would do well to
> > look over their material:
> >
> > http://www.cincomsmalltalk.com/userblogs/cincom/blogView?content=tutorials
>
> <personal_opinion>
>
> This is an excellent tutorial, and I hope our squeak tutorial
> can be of similar quality. However, I think this tutorial is
> unsuitable to a reader who is already familiar with blocks,
> loops, classes, and methods. If one understands these topics,
> the density of new information in the first tutorial is very
> low. Our tutorial should be much shorter and denser, since we
> are assuming that the reader already understands blocks, loops,
> classes, and methods. I did not look at the second tutorial.
>
> Also, the example of reading a log file did not seem very
> interesting or exciting to me; it is also not a typical
> application of Squeak.
>
> </personal_opinion>
>
> My idea for a demo application is a mock stock ticker. It would
> consist of two components:
>
> 1.  A data "retrieval" class. This would not retrieve real data,
>     but would make  up companies and numbers and send that data
>     to a client. It would mostly be a wrapper around a
>     Dictionary or something similar; it would be an easy first
>     class to write.  It would also serve to introduce the reader
>     to Collections and to the System Browser.
>
> 2.  A StockTickerMorph. This would take the data from the server
>     class and present it in a "scrolling ticker" widget similar
>     to the one on TV. Again the real functionality is minimal,
>     but it would illustrate how easy it is to create custom
>     animated widgets in Squeak and Morphic (I am assuming it is
>     easy).
>
> I admit that I am partial to pretty animations, and am not
> really interested in routine tasks like parsing log files.
> Also, I want to show the reader that Squeak not only makes
> "easy" things easy (log file inspection), but also makes "cool"
> things easy (animated widgets). I believe that is (or should be)
> a major selling point for Squeak.
>
> I realize I disagree with some of you about what should be in
> the tutorial, and what applications are interesting. Most of
> this disagreement can be summarized in three words: Morphic vs.
> Seaside. I am on the Morphic side, and Bakki and Chris seem to
> be on the Seaside side (Jason and Derek have not expressed an
> opinion). I cannot predict whether a beginner will be more
> interested in rich client development (Morphic), or web
> development (Seaside), and a including both in a single tutorial
> would make the tutorial broad rather than focused. Thus, I
> think that we should include one in the tutorial and save the
> other for later.
>
> Why should Morphic be in the beginners tutorial, rather than
> Seaside?
> * Morphic comes with the default Squeak image
> * Craig Latta wants a beginners tutorial on Morphic
> * Morphic is "cooler" than web development
>
> We could maintain a separate Seaside tutorial. However, we do
> not currently have the organizational capacity to focus on more
> than one project. I have said before:
>
> The reason that previous documentation efforts failed is the
> lack of focus. To succeed, we must press ahead. There is no
> "ahead" unless we set a goal and work toward it. Our current
> goal is reasonably small and well-defined. By achieving a small
> goal, we will prove to the community and to ourselves that we
> can achieve progressively bigger and better goals. Focus on the
> task at hand; everything else will come in time.
>
> > I am also willing to edit and prepare content provided by others.
>
> Welcome to the team!
>
> --
> Matthew Fulmer
>
>