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@lists.squeakfoundation.org To: squeak-doc@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
On Fri, Mar 30, 2007 at 05:14:14PM +0000, max@nbtsc.org wrote:
For some reason, the mailing list software (or my mail client) retained Matthew's address instead of substituting the list's.
Use the "Reply all" or "Reply to list" rather than the "Reply" feature of your mail program. Reply (by default), sends a message to only the sender of the email; the others send a message to the sender and all recipients, in this case, the whole mailing list.
On Fri, Mar 30, 2007 at 05:14:14PM +0000, max@nbtsc.org wrote:
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 did not find it all at once. I found most of the tutorials on listed on a few pages that had much shorter lists of tutorials. You can see what sites I imported the list from; in the "Links and Sources" section, they are marked with [Links Imported].
I have been stockpiling links ever since I started the doc team; whenever I came across something I hadn't seen before, either from a Google search, mailing list post, or IRC message, I write it in the Swiki for later examination. That is where all the links in the tutorial list came from.
Regarding Stepping through the Swiki; I tried doing that once, before I started the tutorial list, but I didn't get much done as I had no real goal back then. Perhaps it would be more useful now to at least make sure all the pages have a few appropriate links to them, as that would aid in the construction of a "Squeak Index".
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.
Sounds like a really good idea, except, it would be better for this documentation to be based in a Squeak image, so that it could be tested, and code snippets run directly from the docs. Of course, we would have it available on the web as well; hopefully, both would keep each other up-to-date. Other than that, it sounds great.
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.
All of the above exists in very complete form, but needs to be compiled. I know where this stuff is if you want to index it.
- Intro to Morphic
This kind of exists. There is a bunch of stuff on the Swiki about Morphic, but I haven't really looked at what is there.
- FAQ
The Squeak FAQ has very little bearing on reality and probably needs to be completely re-written.
- (eventually, maybe) a design patterns how-to
There are some of these around, and they are very good, but they are a little harder to find. One of the best is the "Bowling for Smalltalk" series near the top of my tutorial list.
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.
No; official documentation is a really good idea. It should exist, but does not. Quite a few in the community have grown to distrust documentation, because it is probably out of date, and so they don't write documentation, because it will fall out of date. Goran's Magic Book is really the only way I know of that we could get and stay out of this loop in the long run. Until I or someone else create it, all we can do is to is get content ready to put into it.
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 PDF's or anything too fancy from my phone browser.
Cool. Nearly all the documentation is HTML on the Swiki; there are a few PDF's and a few Squeak projects, but mostly HTML docs.
Thanks for the motivating example, Matthew. I think we stand a chance of doing a real service to the Squeak community here.
Indeed. Documentation is the biggest hurdle that exists for everyone involved or seeking to be involved in Squeak. The problem is most obvious with newcomers, but is just as bad for an expert who is trying to understand an unfamiliar package. Source code can only go so far. It can never tell you why it is one way and where it fits into the larger system.
So, here is what I think what we should do for the next few months is finish the tutorial list, then similarly tackle the other major problems on the Swiki: http://wiki.squeak.org/squeak/2352
Once we have those bugs resolved, we will have enough good, up-to-date documentation that we can start seriously thinking about long-term maintenance. If that sounds like a good plan, I will summarize it and put it on the Swiki.
squeak-doc@lists.squeakfoundation.org