Adrian, that is exactly my idea too! That way the active newcommers like Sophie can easily help documenting the code by simply adding their notes, thoughts and suggestions in their own style, while in the next step someone more "professional", that is, more knowledgeable documenter can extract from this valuable contribution from fresh minds into the "official" code comments.
Happy New Year for Pharo and to all Pharoers! JAnko On 31. 12. 2009 19:30, Adrian Lienhard wrote: > What about using a wiki to gather and edit comments (as suggested by > Stan) and then integrate them in a second step so that they are kept > together with the code (as suggested by Stef)? Just a thought... > > Cheers > Adrian > > On Dec 31, 2009, at 18:09 , Stéphane Ducasse wrote: > >> Stan >> >> My point is not to discourage you. :) >> Documentation is a state of mind and a large valuable job. >> Now we can do the same as you said (a guy ask and the others try to >> answer >> and we write comments that are pushed into the system). >> >> A first step is >> - make a list of the classes that are missing comments: >> - pick one a week and via the mailing-list make it better and after >> we integrate it. >> First it would be fun and we would get one class commented at the >> end of the week. >> >> Stef >> >> >>>> >>>> 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 -- Janko Mivšek AIDA/Web Smalltalk Web Application Server http://www.aidaweb.si _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
