>From my experience with Seaside I can only give these (rather pessimistic) comments:
- In Seaside we have the policy that every public class and every public method is commented. We are not there yet with all the code, but we have a few packages that have 100% comment coverage. The disappointing thing is that there are still questions where we can point the reader to the method or simply copy and paste the method comment in question. People don't read comments, even if they are at their finger-tips. I think that even less people would read them when they were in a web-browser. - We've been asking people to help with class comments for many years already, but the contributions have been minor. A few people pointed out spelling errors and one person contributed some class comments. Another problem is that outsiders often do not have the knowledge to write class comments, after all they are the target audience. Users of the code don't have the time to write a comment. They want to get their code running after figuring out how it works. This is only the developer that writes them, if anybody. - Separating documentation from code doesn't work. Early versions of Seaside had part of the documentation externalized in Wikis. This documentation quickly out-dates and potentially misguides readers with wrong information for many years. Also have a look at how other open source projects dealt with this in the past. PrototypeJS and script.aculo.us has a wiki for many years: I think they lost popularity mostly because they could not keep the documentation and examples accurate and in sync with the code. They fixed that now and create accurate documentation from the code. Lukas -- Lukas Renggli http://www.lukas-renggli.ch _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
