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 >> >> >> >> >> >> >> >> >> >> >> -- >> View this message in context: >> http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-knowledge-Knowledge-reuse-tp4236694p4237040.html >> Sent from the Pharo Smalltalk mailing list archive at Nabble.com. >> >> _______________________________________________ >> Pharo-project mailing list >> [email protected] >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > _______________________________________________ > Pharo-project mailing list > [email protected] > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
