But you know you can also propose a solution with code. :) Take DrDoc and improve it. I agree more than 200% with you but my day job in not improving pharo or squeak. Pharo is a nice project but I have plenty of other things that I have to do (admin, research, PhD students....) Stef
So far we should invent it. And I totally agree with you. If people do not see the good doc they will not write good comment. I started to work on DrDoc a kind of package meta data to add documentation to a package but it got stole I should push that again. What would be nice is to take one package and do it well as an example.
It think it should be possible to write documentation at the package level. So developpers have a place where they can write an overview of their package. When we click on a package, documentation should be displayed by default or easily.
Yes! Here is a post I made in April of 2003:
The biggest frustration with using comments is that there is no good "starting place" for a given class category. For example, go browse the Seaside classes and categories and figure out where one should start. You can repeat this exercise for any number of categories. I propose that we we add a documentation attribute to the PackageInfo stuff, so there is a category level documentation spot, with links to the appropriate class comments.
Any thoughts? I didn't get any response, and I sent a similar type of thought to Stef recently, but he's so busy I don't even know if he read my email :)
- Brian
In the rubygems world, it is a common practice to write documentation in a README file which is displayed by RDoc on startup page (github works the same way). It seems to me that there's the same level of comment between Ruby class/methods and Pharo. The documentation at the package level may be the difference.
Python has a real documentation effort.Each release come with its up to date documentation. It's a release criteria. Python shares some similarities with Pharo as they both have "batteries included". May be there should have a process to contribute to a centralized Pharo documentation which can be accessed within the IDE.
Laurent. _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project