squeak-doc

squeak-doc@lists.squeakfoundation.org

19 discussions

FW: [Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are MISSING
by Ron Teitelbaum 13 Apr '07

13 Apr '07

I'm not sure if you saw this but it looks pretty cool. Ron -----Original Message----- From: seaside-bounces(a)lists.squeakfoundation.org [mailto:seaside-bounces@lists.squeakfoundation.org] On Behalf Of Boris Popov Sent: Friday, April 13, 2007 1:21 PM To: Seaside - general discussion Subject: RE: [Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are MISSING For me, the whole thing about comments is very simple. I use Prototype almost exclusively for most scripting here. Do I ever look at the source code? Yes, on occasion. Do I look at it to figure out how to use it? No, because there's http://www.prototypejs.org/api instead. Let's figure out a good model for creating simple straightforward documentation similar to that one and invite contributions. I know I could spend few minutes every week writing up comments and examples and if all of us did it, we'd have decent documentation in no time. Cheers! -Boris -- +1.604.689.0322 DeepCove Labs Ltd. 4th floor 595 Howe Street Vancouver, Canada V6C 2T5 http://tinyurl.com/r7uw4 boris(a)deepcovelabs.com CONFIDENTIALITY NOTICE This email is intended only for the persons named in the message header. Unless otherwise indicated, it contains information that is private and confidential. If you have received it in error, please notify the sender and delete the entire message including any attachments. Thank you. > -----Original Message----- > From: seaside-bounces(a)lists.squeakfoundation.org [mailto:seaside- > bounces(a)lists.squeakfoundation.org] On Behalf Of Jason Johnson > Sent: Friday, April 13, 2007 10:12 AM > To: Seaside - general discussion > Subject: Re: [Seaside] Re: Why seaside really sucks! COMMMMMMMENTS are > MISSING > > nicolas cellier wrote: > > Comments should also tell about implicit conventions. > > Remember my post on squeak dev about morphic heading > > > > I do not know the unit (degrees radians ?) > > I do not know the origin (toward upscreen, right ?) > > I do not know direction (clockwise, counter clockwise ?) > > > > Reverse engineering the code is not the fastest way to the > information... > > > > As for the first person, remember objects know about themselves, this > > is called reflexivity (self = ego = I). > > > > Nicolas > Yes, those are good things that need to be documented. And no, one > shouldn't have to dig through source to find out what a method is called > with. I'm not against documentation and I'm not against comments. But > I mean, just because something is a comment doesn't mean it is good. It > is possible to write bad comments as well (e.g. commenting every line > telling what that line does. We're not coding in assembler after all). > > So to phrase it another way: Good comments are good, bad comments are > bad. :) > _______________________________________________ > Seaside mailing list > Seaside(a)lists.squeakfoundation.org > http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside _______________________________________________ Seaside mailing list Seaside(a)lists.squeakfoundation.org http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

1 0

[Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING
by Paul Bennett 12 Apr '07

12 Apr '07

Ron - thanks for posting Stephane's email. And I apologise up front if the following seems like the mindless rant of a noob. I think Ron is spot on with suggesting Seaside as a good starting point. A big reason is that it *is* the very reason I am involved with the Squeak Doc Project. A week ago I contacted Lukas Renggli by email about Seaside and Pier. My purpose was to get permission to "refactor" his writings into something more accessible to noob's - something I thought I could do as I learnt it for myself. He gave his permission and then suggested I write to the Pier list about what I am doing. Unfortunately the only response was to go join the Squeak Doc Team. So I did. But with interest in a documentation effort by Lukas, and now by Stephane, there may be the interest needed to make it successful. Here's some personal history (hope I don't bore anyone): I'm not a programmer (well, not yet). I'm interested in products that can help companies that I work for and web frameworks are a big part of that. That is how I got to ST and Squeak - by finding out about Seaside. I just mucked around on the Seaside and Pier websites and dove into the frameworks and realised that as a noob I was absolutely lost. And the more I looked for information the more I realised there is none for a person at my level. OK - there are some high level descriptions, but nothing that made the framework accessible to me. So I thought - this is open source, it's about pitching in - why don't I write it myself! Yeah, it's a bit of a stretch (as you know, Ron, I'm still struggling with basic ST issues). But if I'm going to learn it anyway why don't I write about it and contribute it back to the cause. Because if I got here, there will be others behind me too, and they will be less forgiving of the lack of documentation and perhaps turn away - which would be a pity. SO - not to lessen the need to document other parts of Squeak and it's core, I do think starting on a project like Seaside would actually benefit the rest of the Squeak community. 1) It is a magnet to ST and Squeak from a growing web community. 2) It seems like a fairly active community, so there is a better chance of it being successful 3) An early success will create momentum in the documentation of other areas/topics. Paul

2 1

FW: [Seaside] Why seaside really sucks! COMMMMMMMENTS are MISSING
by Ron Teitelbaum 06 Apr '07

06 Apr '07

Hi all, I wonder if Seaside would not be a good place to try something out. It would seem that if there was a good way to manage the comment workflow it would be very useful to try it out here. Thoughts? Ron -----Original Message----- From: stephane ducasse This is not easy for me to say that because I appreciate the work of Avi, Lukas and Philippe. But I'm sorry to say that but seaside sucks! Not because of the code or the concepts. But because there is really not enough comments. Really! It is really difficult to understand a simple method is doing and if it makes sense to specialize it. This is TERRIBLE since I think that I'm a good programmer but seaside code prevents me to be fully efficient. I have to guess try and error and guess again. I have to ask stupid questions to the mailing-list while I would prefer to use it for interesting questions. I think that seaside goes even against the philosophy of Smalltalk (a system that someone alone can understand) because this total lacks of comments is TRAPPING me. I cannot use my skills full speed. Thanks what a great feeling. pleaseeeeeee do not tell me to read the code or to use senders! This is really the worse answer I can get. I always hated this kind of answer on smalltalk forums. (Please do not ask me what I'm doing to improve the situation because people knows what I did for seaside and Smalltalk already.) I think that as a community we should do something especially since we have monticello and comments could be easily merged. I pushed a lot seaside and I'm trying to push it again further but come on we should WAKE UP! I would really like that people with knowledge helps improving the situation. So if you think that seaside is cool and it is worth more, spend 30 min of your precious time and add comments, help lukas and the other to make Seaside really a habitable piece of code. Comments are for people that do not know or remember. So if you really want to make the community grow you know what you should do. But may be it is better that seaside stays a cool program for a nice and private club after all. Stef PS: I should say that filelibrary is a good start at documenting a functionality. May be adding method comments would help there too. _______________________________________________ Seaside mailing list Seaside(a)lists.squeakfoundation.org http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside

1 0

General thoughts...
by Paul Bennett 06 Apr '07

06 Apr '07

Hi, I'm still getting my head around the magnitude of what I have just volunteered to be a part of. I've griped and groaned before about the seeming lack of information about Squeak / Smalltalk but after perusing the wiki I am astounded by how much is there. Though at this point it's usefulness to me is not determined. Having said that, the following is a regurgitation of what has so far passed through my noob synapses about the topic of Documentation and I offer them as points of discussion... We are working on two concurrent, yet associated, projects... * Squeak Documentation Project * Squeak Tutorial Project (listed as the first project of the Documentation Team) These questions came to mind. 1) Is the current wiki system suitable to handle the end result, and if not, is there something available in Squeak for it? There was a little discussion today in IRC about it. And there is a desire to see magicbook created. But we only have a wiki right now and my thoughts currently are around my understanding that a Wiki is a fairly statically structured system. I sense that what we are looking to produce is going to be significantly dynamic. A static system is going to require a huge amount of effort in maintenance - something we don't seem to access to(yet?!). Also, to get the ideas flowing, what do you think about using concept maps to lay out access to information? Check this link out.... http://www.eiffel.com/developers/learning_maps/ and how about this... http://cmap.ihmc.us/ Perhaps these are tools that could be developed in Squeak? 2) Documenting everything in Squeak is a big task. BIG! At least it looks that way to me. Do we want to include documentation for non- core projects like Seaside and Pier? I ask this because documenting and Tutorialising those two projects is what brought me to the Documentation group to begin with. I can envision a core documentation team assisting with project members documenting their product, but I sense most of them have their own pages they would maintain and the core Documentation team might prompt them annually to add / change material where necessary. 3) Who are the users of the wiki? What do they want from it? How are we going to provide for those needs? Some initial definitions I come up with are... Non-Programer AKA newbies (no programming experience at all) Programmers Switchers (from other languages or other VM's) Intermediate Advanced (do they even visit the wiki?) 4) Presentation of information is almost as important as the content of that information. So thought needs to be given to this area. So look and feel of the wiki adds value to the material presented. 5) We should define the information we want to collect when entering an article/tutorial/link to the wiki. This would act as a guideline for ways to search it later, and to sort by usefuleness. Eg, Published date (eg: older articles might get a lower weighting), Title, Author(s), Topic, Tags, Abstract. Other Random Thoughts -------------------------------- * Have a ratings & comments system for articles (ratings can only be applied by registered Squeakers) * Tags that can be associated with an article so that filtered searches are available I believe in the KISS principle, but the above thoughts might provide for a discussion of a roadmap. Regards Paul

4 5

Roadmap proposal.
by max＠nbtsc.org 05 Apr '07

05 Apr '07

A couple of thoughts on the Doc Project: First, as Matthew points out, the current state of Squeak's documentation is really a "political" (I'd say "cultural") problem, not so much a technical one. I see us maybe getting a bit distracted with all the cool technologies that can be brought to bear on the challenge of having good docs. Technical solutions to cultural problems can only really work to the extent that they are built on a solid grasp of the culture. We're all (to varying extents) newbies on this team, so it behooves us to learn the history, attitudes, and values of the community we're trying to be a useful part of. Squeak's culture, in my limited experience, is messy but friendly, not so different from other mid-size open source projects. We're smart, well-meaning people, scattered around the world. Some are ideologues, some pragmatists. We all have slightly different visions of what we want, and we collaborate to the extent that these visions overlap. However, Smalltalk is different from other programming languages in a number of ways, one of which I think is especially pertinent here, which brings me to my second point: Smalltalk was always intended to be a uniquely user-friendly and readable language, built on a few powerful concepts, with a minimum of arbitrary syntax. I think that the reason the more experienced Squeakers are so lackadaisical about documentation is that well-written Smalltalk IS its own documentation. This is a very good thing! With this in mind, I think that an important guiding principle for this project should be to teach newcomers to read and understand the code first and foremost. Seen in this light, the tutorials are more than just the tip of the iceberg; they may be a significant fraction of the battle. Once a newbie like myself learns to read code to answer specific questions, and learns to use the IDE tools effectively, the remaining need for documentation is mostly for relatively terse, high-level conceptual descriptions of larger systems like Morphic. I would be in favor of focusing on the existing class and method comments, to make them as accurate and helpful as possible, before we go building an extensive parallel doc system. This might be harder or less fun, but I'm convinced it will be more useful in the end. I think that, having done that, there will still be a need for a Magic Book, but the scope of it may be reduced considerably. Also, we'll probably produce better documentation for having taken the time to really get familiar with what we're documenting. Sent via BlackBerry from T-Mobile

3 3

Call for monthly reports
by Matthew Fulmer 31 Mar '07

31 Mar '07

I don't know why I never used the mailing list for this purpose before. It is about time for the monthly report to go out to Squeak-dev, and show them what a great job we are doing. Email me what's up, either in public or private, and I will put it on the list. -- Matthew Fulmer -- http://mtfulmer.wordpress.com/ Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808

1 0

Re: Swiki Organization project Roadmap
by max＠nbtsc.org 31 Mar '07

31 Mar '07

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(a)lists.squeakfoundation.org To: squeak-doc(a)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(a)lists.squeakfoundation.org http://lists.squeakfoundation.org/mailman/listinfo/squeak-doc Sent via BlackBerry from T-Mobile

2 2

Swiki Organization project Roadmap
by Matthew Fulmer 29 Mar '07

29 Mar '07

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

1 0

Documentation Team Update
by Matthew Fulmer 23 Oct '06

23 Oct '06

I spent this Saturday creating several lists of tasks that need to be done to refactor the Swiki [1]. The Swiki is somewhat of a mess, and this page collects together the worst offenders. What is going on in the documentation team? - The beginners tutorial [2] I began writing has stalled. Michael's Morphic example [3] will probably form the bulk of chapters 3 and 4. - Derek O'Connell is working on another Morphic Demo application [4], which may evolve into a general Morphic tutorial - I made a list of all the pages in the Swiki [5], and am working on finding all the lost pages on the Swiki, creating links between pages, and tagging pages that need editing. I also started a diary [6] (news page, blog) for the documentation team. [1]: The Swiki refactoring project: http://minnow.cc.gatech.edu/squeak/2352 [2]: The beginners tutorial project: http://minnow.cc.gatech.edu/squeak/5869 [3]: Michael Davies' Morphic example: http://www.squeaksource.com/SampleImageViewer.html [4]: Derek O'Connell's Morphic examples (in progress): http://minnow.cc.gatech.edu/squeak/5884 [5]: Compiled list of all Swiki pages: http://minnow.cc.gatech.edu/squeak/5587 [6]: Doc team diary: http://minnow.cc.gatech.edu/squeak/812 -- Matthew Fulmer

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

squeak-doc