[Squeak-doc] Re: Swiki Organization project Roadmap

[max at nbtsc.org]

For some reason, the mailing list software (or my mail client) retained Matthew's address instead of substituting the list's. On the assumption that we aren't the only two people here, I'm re-sending this to the list:

------Original Message------
To: Matthew Fulmer
Sent: Mar 30, 2007 10:01 AM
Subject: Re: [Squeak-doc] Swiki Organization project Roadmap

Matthew, your tutorial index seems fairly comprehensive already, in the sense that there's an awful lot of material there to work with. It is a mess, but at least it's all in one place!

How did you find all that stuff? I recall you mentioned "stepping through the swiki", presumably in numerical order. I would be happy to do the same for a range of swiki pages to sort out useful doc content. Just tell me where to start.

I believe that it would be very helpful to both newbies and maintainers to have a reasonably comprehensive unified "official" doc site. This could be kept up to date to reflect changes in Squeak, and could also be improved with input from new Squeakers.

What I have in mind is something web-based and fairly simple, but a little fancier and more stable than the swiki, with content that is easy to read, up to date, and quickly addresses, say, 80% of beginning user's needs for help. For that frustrating final 20%, let there be links to the existing jumble of sites. 

I think this "official" site should include:

- Introduction to Squeak with brief outlines of system architecture and project history.

- Objects, classes, syntax tutorial, how to read code.

- How to use the browsers, debugger, monticello, and other basic IDE tools.

- Intro to Morphic

- FAQ

- (eventually, maybe) a design patterns how-to
 
I'd be happy to undertake writing this stuff or assembling it from some of the current sources (with permission from the authors, of course). I'll need plenty of input from the more experienced, but that shouldn't be too hard to find.

It's also quite possible that having official documentation is somehow a really bad idea, in a way that hasn't occurred to me. If so, please feel free to tell me why.

I can contribute several hours a week worth of actually trying things out in squeak, and more time (during my mindless day job) reading web pages and writing summaries etc. I can't read pdfs or anything too fancy from my phone browser.

Thanks for the motivating example, Matthew. I think we stand a chance of doing a real service to the Squeak community here.


------Original Message------
From: Matthew Fulmer
Sender: squeak-doc-bounces at lists.squeakfoundation.org
To: squeak-doc at lists.squeakfoundation.org
Sent: Mar 29, 2007 10:44 AM
Subject: [Squeak-doc] Swiki Organization project Roadmap

Hello to everyone who is interested in the documentation
project. After a discussion on IRC, I have decided that I am
being too quiet about the documentation project, and I would
like to remedy that. Thus, this is the roadmap of what I have
been working on and how you could help.

The Swiki, the primary source of documentation on Squeak, is
severely disorganized. This is a political problem, I believe.
There are also some technical problems, but they are not as
severe:

- We could migrate the Swiki to a more modern system like Pier
- We could move all the content to Sophie and have it accessible
  in the image as well as the web.
- We could implement MagicBook[1] and be able to find
  out-of-date documentation

However, these technical issues are meaningless while political
problems abound. So, here is a broad overview of what needs to
be done to solve the political problem that Squeak documentation
has no real maintainers:

1. Find all the existing documentation
2. Review it to assess it's quality
3. index it so we know what exists
4. for any projects without documentation, add them to the
   index, and contact the maintainer to try to get some
   documentation

These three steps will require a lot of work, but once finished,
we will have a complete, but messy "first draft" of what the
documentation for squeak should look like. This would be the
time to discuss long-term technical ideas, like maintinance.

How can we index all existing documentation? we need a model of
what such an index should look like, something which is a small
but scalable subset of that index. I have been building a
tutorial index, and I think it serves as a useful model to the
larger documentation index we must eventually create:
http://wiki.squeak.org/squeak/792

Thus, how can we get this project started? 

First, I believe we should finish the tutorial index I have
started. It is a smallish project, and it will help us bootstrap
a political model for assembling larger projects. We need a
political model if we are to ever tackle the huge projects that
face the doc team. 

Please reply with your thoughts, especially if you want to
volunteer.

[1]: MagicBook: http://wiki.squeak.org/squeak/3004

-- 
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808
_______________________________________________
Squeak-doc mailing list
Squeak-doc at lists.squeakfoundation.org
http://lists.squeakfoundation.org/mailman/listinfo/squeak-doc



Sent via BlackBerry from T-Mobile