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-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
