- Pharo-dev - lists.pharo.org

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by Stan Shepherd

StÃ©phane Ducasse wrote: > > Stan > > Outsourcing documentation does not work. > Having tests is one way but comments are crucial. > You see we open issue to fix and add a single comment. > > The way to go is > - having browsers showing doc all the times > (like the old browser was showing the class def and the class comment) > - defining better tools to browse documentation. > I started (but did not finish) to use the new tree developed by alain to > provide a package > |> class > class comment > V method > methodcomment > method > methodcomment > |> class > class comment > |> methods > |> class > class comment > |> methods > > We need a better version of > ClassTree new openOn: Collection > Stef > > StÃ©phane Ducasse wrote: > > Outsourcing documentation does not work. > True, in much the same way as: > it has been said that democracy is the worst form of government except all > those other forms that have been tried from time to time ...Winston > Churchill > In my image there are 905981methods without comments. Assuming 99% are trivial or self documenting, that would mean 9000 comments require documentation. Given that the developers/maintainers have lived this long without documenting these, what level of confidence would you have that people will go back and do so once you offer them the perfect documentation tool? Given a choice of building the next greatest thing, or sitting down to a nice session of documenting, ... On the other hand, you have users ( I think Sophie has been a good example) who work their way through things, ask the questions, get it straight in their own minds, then are happy to share what they have learnt. If you have spent 2 hours or 2 days puzzling something out, then spending another 5 minutes to capture that information for the sake of others is an obvious step. Also, the person using a piece of functionality knows what they find unclear; someone who has been using the software for 4 years would have remarkable insight to be able to put themselves into the place of the new user seeing the code for the first time. For similar reasons, tests are frequently not good documentation. The test writer wants the best way to test 50 similar cases with the least code, so writes some smart code around the tests to do all the setup etc in generic ways. The person seeking documentation wants a simple piece of code to see a function operate, without having to strip away levels of indirection, boilerplate, attractive screen formatting,.... What would be the worst case if all users had a quick way to update documentation? The guardians of a package would review their watchlist once a week, and revert or edit any incorrect documentation. Just the fact of someone trying and failing to explain a method could spur the author to provide a better explanation. A useful social contract would grow up, where the developer agrees to answer questions, and the questioner agrees to make the first cut at documenting the answer. There could be a change in the culture of doing without documentation, and (I believe) a rapid improvement in the completeness of documentation. And imagine if the quality and completeness of the documentation became a positive selling point for Pharo. As Mariano said about the release images, what a shame to build the perfect system but only a dozen people be able to use it. Thanks to all the contributors for your great work. Help us to help you to finish it to showroom standard. ...Stan -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-know… Sent from the Pharo Smalltalk mailing list archive at Nabble.com.

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by Levente Uzonyi

On Thu, 31 Dec 2009, Lukas Renggli wrote: >> Anyway, the +10 bounty for a regex solution is still open! > > 'bar' asRegex copy: 'foobarqux' replacingMatchesWith: 'XYZ' Or: 'foobarqux' copyWithRegex: 'bar' matchesReplacedWith: 'XYZ' Levente > > Lukas > > -- > Lukas Renggli > http://www.lukas-renggli.ch > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >

Dec. 31, 2009

Re: [Pharo-project] Can't debug in 1.1

by Martin McClure

StÃ©phane Ducasse wrote: > Probably the changes of Martin von Lowis. > I imagine that when marcus is bad from holidays he can tell us more. > > Now I try to reproduce it in 11128. > > I put a self halt in a method and execute the method. > And I got no problem. > After I tried to select 'self halt' + doit in the debugger itself and it worked too. > > Did you have a way reproduce it systematically ? Where did you get your image from? If you had an older image and applied updates the corruption may not be there. For me, it reproduces 100% in a downloaded pharo1.1-11112-alphadev09.12.2 image, and it also reproduced it in that image with all updates applied, and I may have also had this problem in the latest core download. Regards, -Martin > On Dec 31, 2009, at 4:17 AM, Martin McClure wrote: > >> This one's pretty nasty. >> >> Symptom: >> >> The debugger in recent and current 1.1 images is completely broken. >> >> To reproduce (save your image first!): >> >> "self halt" doit. It goes into an infinite loop, and if there's a way to >> get out of that without killing the VM I'd like to know about it. Alt-. >> works, but just tries to open another debugger, which goes into another >> infinite loop, etc. >> >> >> >> Cause: >> >> DebuggerMethodMap>MapCache is a WeakIdentityKeyDictionary, but it is >> corrupt. It has an array of 22 nils, expired is 0, so it contains >> nothing, but tally=16. >> >> This causes MapCache to lie about its size. >> >> This drives DebuggerMethodMap class>>cacheDebugMap:forMethod: into an >> infinite loop, the whileTrue: condition is always true, it keeps trying >> to remove non-existent elements to get the size to be less than 16 but >> the size is always 16. >> >> I don't see any obvious code paths to get into this state. I suspect it >> may have been left in this state when weak collections were updated with >> the new code not too long ago. >> >> >> Cure: >> >> In an inspector, set tally=0. Debuggers then work again. >> >> Not sure how to package this as a slice, so I'll leave the update to >> someone else, and get back to hashing, which was hard when every >> walkback froze my system :-) >> >> >> Regards, >> >> -Martin

Dec. 31, 2009

Re: [Pharo-project] Cannot even browse a class in web image

by Schwab,Wilhelm K

Fair enough, but anything that we know how to fix should be fixed, if only by a file-in after the build, before the images are posted. -----Original Message----- From: pharo-project-bounces(a)lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Lukas Renggli Sent: Thursday, December 31, 2009 6:03 AM To: Pharo-project(a)lists.gforge.inria.fr Subject: Re: [Pharo-project] Cannot even browse a class in web image > OK, thanks Lukas! But you see that we have a serious problem?Â How many time you heard "I have already fix this in ....."Â or "This bug is present again" The problem is that nobody uses O2 12 hours a day and really cares to fix things on the fly all the time. I do that with OB and RB on a daily bases. It consumes some time here and then, but it is fun, makes me more productive and in the long run pays off. Lukas -- Lukas Renggli http://www.lukas-renggli.ch _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009

Re: [Pharo-project] Pharo testers.... WE NEED YOU!!!

by Schwab,Wilhelm K

Same here: Linux, and (as infrequently as possible) Windows. Bill ________________________________ From: pharo-project-bounces(a)lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Benoit St-Jean Sent: Thursday, December 31, 2009 10:37 AM To: Pharo-project(a)lists.gforge.inria.fr Subject: Re: [Pharo-project] Pharo testers.... WE NEED YOU!!! Count me in for beta testing... ----------------- Benoit St-Jean Yahoo! Messenger: bstjean Blog: lamneth.wordpress.com A standpoint is an intellectual horizon of radius zero. (Albert Einstein) ________________________________ From: StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> To: Pharo-project(a)lists.gforge.inria.fr Sent: Thu, December 31, 2009 10:25:28 AM Subject: Re: [Pharo-project] Pharo testers.... WE NEED YOU!!! sd -> mac On Dec 31, 2009, at 4:14 PM, Benoit St-Jean wrote: > I suggest that, at a minimum, we specify on which platform each developer intends to test. > > ----------------- > Benoit St-Jean > Yahoo! Messenger: bstjean > Blog: lamneth.wordpress.com > A standpoint is an intellectual horizon of radius zero. > (Albert Einstein) > > > From: Mariano Martinez Peck <marianopeck(a)gmail.com<mailto:marianopeck@gmail.com>> > To: Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > Sent: Thu, December 31, 2009 7:29:46 AM > Subject: Re: [Pharo-project] Pharo testers.... WE NEED YOU!!! > > Ok....thanks to all. I created this page: http://code.google.com/p/pharo/wiki/ListOfBetaTesters > > We only need the confirmation from Demian. > > Have a happy new year! > > Mariano > > ps: leaving to paris :) > > On Thu, Dec 31, 2009 at 1:11 PM, Alexandre Bergel <alexandre(a)bergel.eu<mailto:alexandre@bergel.eu>> wrote: > Count on me as well Mariano. > > Alexandre > > > On 31 Dec 2009, at 12:40, Mariano Martinez Peck wrote: > > > > > > > On Thu, Dec 31, 2009 at 12:29 PM, Tudor Girba > > <tudor.girba(a)gmail.com<mailto:tudor.girba@gmail.com>> wrote: > > Hi, > > > > I would like to participate (within some time constraints). > > > > Excellent. No, there will not be any time constraints. I say just a > > few days, to express that we need really test it, at least for a > > several hours. All of us are doing this as a Hobie. So, not press. > > The worst thing that can happens is that the rest of the testers > > test it, (you don't) and the image is released. > > But there is no problem at all, next image :) > > > > > > I can test > > the loading and the development of Moose in that image. I am working > > on a Mac. > > > > > > Cool!! But the problem is not only the load, but the use in itself. > > Look, the script seemed to work. I "loaded" everything, but then.... > > > > > > Cheers, > > Doru > > > > On 31 Dec 2009, at 12:12, Stan Shepherd wrote: > > > > > > > > > > > > > > Mariano Martinez Peck wrote: > > >> > > >> Ok, you already know the idea. Damien, or the person that build the > > >> next > > >> Pharo dev and web images will send those Pharo beta testers a > > private > > >> email > > >> with the link to download the image. No ANN and now update is done > > >> yet to > > >> the website. Then the betatesters use that image as much as > > >> possible for a > > >> couple of days. Report bugs if necessary and if it is ok, the image > > >> is > > >> released. > > >> > > >> Regarding the list of beta testers would be perfect if we cover the > > >> combination of OS (Linux, Mac, Windows) and the browser (OB, O2). > > >> But we > > >> cannot pretend too much. Take into account that not all the people > > >> can > > >> work > > >> with a new image very easily because they have to migrate data > > >> ...etc..Others can just download the project from MC and start to > > >> work :) > > >> > > >> So...here is the list, if you offer yourself, it would be cool to > > >> know: > > >> OS, > > >> VM version, Dev or Web, browser you usually work, 32 o 64 bits, > > >> I will then collect this and I will put it in the wiki. > > >> > > >> - Mariano Martinez Peck. Mac OS, Squeak 4.2.2beta1U.app, Dev, OB, > > >> 32 > > >> bits > > >> - Stan Shepherd > > >> > > >> > > >> WHO ELSE IS IN THE LIST ?? > > >> > > >> cheers and happy new year!! > > >> > > >> _______________________________________________ > > >> Pharo-project mailing list > > >> Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > > >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > >> > > > Ubuntu 9.04, > > > VM: unix - i686 - linux-gnu - Pharo0.1 of 16 May 2008 [latest > > update: > > > #10074] > > > Web > > > OB (would also used package browser if working) > > > 32 bit > > > ...Stan > > > > > > -- > > > View this message in context: http://n2.nabble.com/Pharo-testers-WE-NEED-YOU-tp4235920p4235982.html > > > Sent from the Pharo Smalltalk mailing list archive at Nabble.com. > > > > > > _______________________________________________ > > > Pharo-project mailing list > > > Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > -- > > www.tudorgirba.com<http://www.tudorgirba.com> > > > > "In a world where everything is moving ever faster, > > one might have better chances to win by moving slower." > > > > > > > > > > _______________________________________________ > > Pharo-project mailing list > > Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > _______________________________________________ > > Pharo-project mailing list > > Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > -- > _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: > Alexandre Bergel http://www.bergel.eu > ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. > > > > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > Yahoo! Canada Toolbar : Search from anywhere on the web and bookmark your favourite sites. Download it now! > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr<mailto:Pharo-project@lists.gforge.inria.fr> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project ________________________________ Make your browsing faster, safer, and easier with the new Internet ExplorerÂ® 8. Optimized for Yahoo! Get it Now for Free! <http://downloads.yahoo.com/ca/internetexplorer/>

Dec. 31, 2009

Re: [Pharo-project] Pharo-beginner mailing list ?

by csrabak＠bol.com.br

Janko, As in Smalltalk we really care about names, I vote for maintaining the name "project" as the intended audience of this list is to gather developers and early users so even who has less skill or inclination to do coding can contribute with suggestions and bug reports. my 0.019999.... -- Cesar Rabak Em 31/12/2009 05:48, Janko MivÅ¡ek <janko.mivsek(a)eranova.si> escreveu: Hi guys! Maybe it could be good idea to rename this list to pharo-dev? pharo-user, pharo-dev, a perfect balance in name and content :) Best regards Janko On 30. 12. 2009 18:46, StÃ©phane Ducasse wrote: > ok let us wait to get more feedback on the idea... > > Stef -- Janko MivÅ¡ek AIDA/Web Smalltalk Web Application Server http://www.aidaweb.si _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by Lukas Renggli

> Anyway, the +10 bounty for a regex solution is still open! 'bar' asRegex copy: 'foobarqux' replacingMatchesWith: 'XYZ' Lukas -- Lukas Renggli http://www.lukas-renggli.ch

Dec. 31, 2009

Re: [Pharo-project] Developer guide ... ?

by csrabak＠bol.com.br

Bill, Perhaps what I wrote wasn't so clear and I thought I'd put a context when I commented that my ramblings were not about the 'systems' parts which is how I see your observation, and I agree on that. In fact, save some specifics which a plugin makes sense, probably doing in Smalltalk could make the platform more competitive and not only another 'weird syntax' for gluing some other's else libraries. Now, what I was thinking about we have not resources is the big echo systems we need to connect to, for example large packages (ERP/CRM systems), nowadays a hot subject is "Sharepoint integration" but there many others. I believe we should not attempt to write competitive replacements for these as we don't have the resources (not only technical but marketing as well). -- Cesar Rabak Em 31/12/2009 00:17, Schwab,Wilhelm K <bschwab(a)anest.ufl.edu> escreveu: Cesar, Sometimes rewriting is exactly the right thing to do. For example, Object Arts wrapped the Microsoft XML library. First, there is the question of untrusted input and MS binaries (yikes!!!), but also, any time bad input went into it, it would fire off an error with no indication of where it got into trouble. For some reason, MS did not think to take an IStream pointer that would have allowed one to check the position. For an http client, OA again wrapped MS binaries, complete with the typical punishing timeouts under MS control, and being hobbled if IE had been set (or set itself) to work offline. Dolphin is a wonderful product, but users would have been better served with home-grown code in those cases. Bottom line: I think we should rewrite when it makes sense to do so, and wrap just about anything that makes sense for interoperability. Clearly there is a lot to wrap, and priorities must be set, as it will often fall on an individual to do the dirty work. SSL is a no-brainer. Bill -----Original Message----- From: pharo-project-bounces(a)lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of csrabak(a)bol.com.br Sent: Wednesday, December 30, 2009 8:59 PM To: Pharo-project(a)lists.gforge.inria.fr Subject: Re: [Pharo-project] Developer guide ... ? Bill, I think you nailed it precisely! Although all 'systems' working in Pharo will not be enough if we cannot connect and integrate with the leading technologies that we cannot afford to displace/emulate/write in Pharo smalltalk. -- Cesar Rabak Em 30/12/2009 22:54, Schwab,Wilhelm K escreveu: Levente, I'll give you a pass on RPC, on SOAP for sure, and _almost_ on CORBA :) However, a culture of dismissing important things as crap lead us to a point approaching 15 years into Squeak's existence where it does not have ready access to SSL. I know about stunnel, but that is more cheat than fix. Pharo needs to embrace the worthy or we will still be on the fringe 15 years from now, and that would be tragic. Bill _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009

Re: [Pharo-project] Pharo testers.... WE NEED YOU!!!

by Benoit St-Jean

Count me in for beta testing... ----------------- Benoit St-Jean Yahoo! Messenger: bstjean Blog: lamneth.wordpress.com A standpoint is an intellectual horizon of radius zero. (Albert Einstein) ________________________________ From: StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> To: Pharo-project(a)lists.gforge.inria.fr Sent: Thu, December 31, 2009 10:25:28 AM Subject: Re: [Pharo-project] Pharo testers.... WE NEED YOU!!! sd -> mac On Dec 31, 2009, at 4:14 PM, Benoit St-Jean wrote: > I suggest that, at a minimum, we specify on which platform each developer intends to test. > > ----------------- > Benoit St-Jean > Yahoo! Messenger: bstjean > Blog: lamneth.wordpress.com > A standpoint is an intellectual horizon of radius zero. > (Albert Einstein) > > > From: Mariano Martinez Peck <marianopeck(a)gmail.com> > To: Pharo-project(a)lists.gforge.inria.fr > Sent: Thu, December 31, 2009 7:29:46 AM > Subject: Re: [Pharo-project] Pharo testers.... WE NEED YOU!!! > > Ok....thanks to all. I created this page: http://code.google.com/p/pharo/wiki/ListOfBetaTesters > > We only need the confirmation from Demian. > > Have a happy new year! > > Mariano > > ps: leaving to paris :) > > On Thu, Dec 31, 2009 at 1:11 PM, Alexandre Bergel <alexandre(a)bergel.eu> wrote: > Count on me as well Mariano. > > Alexandre > > > On 31 Dec 2009, at 12:40, Mariano Martinez Peck wrote: > > > > > > > On Thu, Dec 31, 2009 at 12:29 PM, Tudor Girba > > <tudor.girba(a)gmail.com> wrote: > > Hi, > > > > I would like to participate (within some time constraints). > > > > Excellent. No, there will not be any time constraints. I say just a > > few days, to express that we need really test it, at least for a > > several hours. All of us are doing this as a Hobie. So, not press. > > The worst thing that can happens is that the rest of the testers > > test it, (you don't) and the image is released. > > But there is no problem at all, next image :) > > > > > > I can test > > the loading and the development of Moose in that image. I am working > > on a Mac. > > > > > > Cool!! But the problem is not only the load, but the use in itself. > > Look, the script seemed to work. I "loaded" everything, but then.... > > > > > > Cheers, > > Doru > > > > On 31 Dec 2009, at 12:12, Stan Shepherd wrote: > > > > > > > > > > > > > > Mariano Martinez Peck wrote: > > >> > > >> Ok, you already know the idea. Damien, or the person that build the > > >> next > > >> Pharo dev and web images will send those Pharo beta testers a > > private > > >> email > > >> with the link to download the image. No ANN and now update is done > > >> yet to > > >> the website. Then the betatesters use that image as much as > > >> possible for a > > >> couple of days. Report bugs if necessary and if it is ok, the image > > >> is > > >> released. > > >> > > >> Regarding the list of beta testers would be perfect if we cover the > > >> combination of OS (Linux, Mac, Windows) and the browser (OB, O2). > > >> But we > > >> cannot pretend too much. Take into account that not all the people > > >> can > > >> work > > >> with a new image very easily because they have to migrate data > > >> ...etc..Others can just download the project from MC and start to > > >> work :) > > >> > > >> So...here is the list, if you offer yourself, it would be cool to > > >> know: > > >> OS, > > >> VM version, Dev or Web, browser you usually work, 32 o 64 bits, > > >> I will then collect this and I will put it in the wiki. > > >> > > >> - Mariano Martinez Peck. Mac OS, Squeak 4.2.2beta1U.app, Dev, OB, > > >> 32 > > >> bits > > >> - Stan Shepherd > > >> > > >> > > >> WHO ELSE IS IN THE LIST ?? > > >> > > >> cheers and happy new year!! > > >> > > >> _______________________________________________ > > >> Pharo-project mailing list > > >> Pharo-project(a)lists.gforge.inria.fr > > >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > >> > > > Ubuntu 9.04, > > > VM: unix - i686 - linux-gnu - Pharo0.1 of 16 May 2008 [latest > > update: > > > #10074] > > > Web > > > OB (would also used package browser if working) > > > 32 bit > > > ...Stan > > > > > > -- > > > View this message in context: http://n2.nabble.com/Pharo-testers-WE-NEED-YOU-tp4235920p4235982.html > > > Sent from the Pharo Smalltalk mailing list archive at Nabble.com. > > > > > > _______________________________________________ > > > Pharo-project mailing list > > > Pharo-project(a)lists.gforge.inria.fr > > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > -- > > www.tudorgirba.com > > > > "In a world where everything is moving ever faster, > > one might have better chances to win by moving slower." > > > > > > > > > > _______________________________________________ > > Pharo-project mailing list > > Pharo-project(a)lists.gforge.inria.fr > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > _______________________________________________ > > Pharo-project mailing list > > Pharo-project(a)lists.gforge.inria.fr > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > -- > _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: > Alexandre Bergel http://www.bergel.eu > ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. > > > > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > Yahoo! Canada Toolbar : Search from anywhere on the web and bookmark your favourite sites. Download it now! > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project __________________________________________________________________ Yahoo! Canada Toolbar: Search from anywhere on the web, and bookmark your favourite sites. Download it now http://ca.toolbar.yahoo.com.

Dec. 31, 2009

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by StÃ©phane Ducasse

Stan Outsourcing documentation does not work. Having tests is one way but comments are crucial. You see we open issue to fix and add a single comment. The way to go is - having browsers showing doc all the times (like the old browser was showing the class def and the class comment) - defining better tools to browse documentation. I started (but did not finish) to use the new tree developed by alain to provide a package |> class class comment V method methodcomment method methodcomment |> class class comment |> methods |> class class comment |> methods We need a better version of ClassTree new openOn: Collection Stef On Dec 31, 2009, at 4:20 PM, Stan Shepherd wrote: > > Situation > ----------- > Pharo/Squeak is potentially a very productive development environment. It > has not achieved the widespread use in production systems that we feel it > deserves. > > Complication > ----------------- > The Pharo world relies on a few people with a lot of knowledge. Starting to > use Pharo means relying on those people to provide the knowledge they have. > The knowledge that is transferred this way is not captured for reuse. Lack > of documentation is usually cited by people evaluating Pharo/Squeak for new > projects. > > For example > "#addScript: and #addStyle: are actually ment for internal use. It is > currently used by the methods WAComponent>>#styles and > WAComponent>>#scripts." > http://n4.nabble.com/Script-in-head-tag-td98415.html > > This is not in the comments. It is tacit knowledge. I'm sure you know of > similar examples; they are not rare. > > Resolution > ------------- > If documentation maintenance were separated from code maintenance, this > tacit knowledge could be captured immediately, by the person who requested > it. Maintaining documentation then becomes largely a task for the users of > the system. > > Action > -------- > One possible mechanism would be to place comments in a wiki. For each class, > and each method of that class, there would be a corresponding wiki section. > Any user could update the comment at any time. The developer/maintainer of > that class could revert any inaccurate edits with one click. Incorrect edits > would not affect the function of a method, hence no requirements to unit > test / integration test. > > Commits of code would ideally also update the wiki comment section. There is > obviously potential for some problems here, but a wiki structure would make > it easy to identify/reconcile parallel edits. > > When a build happens, a process would update the source with latest comments > from the wiki. > > Plan > ---- > I'd be willing to put some time into a proof of concept, if people agree > that it's worthwhile and they would use it. > > Any thoughts? ...Stan > > P.S. Other areas that could be maintained this way: > > Welcome information workspace on download images. > Known problems. > (Examples of class use) > ... > -- > View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-know… > Sent from the Pharo Smalltalk mailing list archive at Nabble.com. > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009