squeak-doc April 2007

squeak-doc@lists.squeakfoundation.org

6 participants
5 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

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

squeak-doc April 2007