[Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.
Situation ----------- Pharo/Squeak is potentially a very productive development environment. It has not achieved the widespread use in production systems that we feel it deserves. Complication ----------------- The Pharo world relies on a few people with a lot of knowledge. Starting to use Pharo means relying on those people to provide the knowledge they have. The knowledge that is transferred this way is not captured for reuse. Lack of documentation is usually cited by people evaluating Pharo/Squeak for new projects. For example "#addScript: and #addStyle: are actually ment for internal use. It is currently used by the methods WAComponent>>#styles and WAComponent>>#scripts." http://n4.nabble.com/Script-in-head-tag-td98415.html This is not in the comments. It is tacit knowledge. I'm sure you know of similar examples; they are not rare. Resolution ------------- If documentation maintenance were separated from code maintenance, this tacit knowledge could be captured immediately, by the person who requested it. Maintaining documentation then becomes largely a task for the users of the system. Action -------- One possible mechanism would be to place comments in a wiki. For each class, and each method of that class, there would be a corresponding wiki section. Any user could update the comment at any time. The developer/maintainer of that class could revert any inaccurate edits with one click. Incorrect edits would not affect the function of a method, hence no requirements to unit test / integration test. Commits of code would ideally also update the wiki comment section. There is obviously potential for some problems here, but a wiki structure would make it easy to identify/reconcile parallel edits. When a build happens, a process would update the source with latest comments from the wiki. Plan ---- I'd be willing to put some time into a proof of concept, if people agree that it's worthwhile and they would use it. Any thoughts? ...Stan P.S. Other areas that could be maintained this way: Welcome information workspace on download images. Known problems. (Examples of class use) ... -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
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 On Dec 31, 2009, at 4:20 PM, Stan Shepherd wrote:
Situation ----------- Pharo/Squeak is potentially a very productive development environment. It has not achieved the widespread use in production systems that we feel it deserves.
Complication ----------------- The Pharo world relies on a few people with a lot of knowledge. Starting to use Pharo means relying on those people to provide the knowledge they have. The knowledge that is transferred this way is not captured for reuse. Lack of documentation is usually cited by people evaluating Pharo/Squeak for new projects.
For example "#addScript: and #addStyle: are actually ment for internal use. It is currently used by the methods WAComponent>>#styles and WAComponent>>#scripts." http://n4.nabble.com/Script-in-head-tag-td98415.html
This is not in the comments. It is tacit knowledge. I'm sure you know of similar examples; they are not rare.
Resolution ------------- If documentation maintenance were separated from code maintenance, this tacit knowledge could be captured immediately, by the person who requested it. Maintaining documentation then becomes largely a task for the users of the system.
Action -------- One possible mechanism would be to place comments in a wiki. For each class, and each method of that class, there would be a corresponding wiki section. Any user could update the comment at any time. The developer/maintainer of that class could revert any inaccurate edits with one click. Incorrect edits would not affect the function of a method, hence no requirements to unit test / integration test.
Commits of code would ideally also update the wiki comment section. There is obviously potential for some problems here, but a wiki structure would make it easy to identify/reconcile parallel edits.
When a build happens, a process would update the source with latest comments from the wiki.
Plan ---- I'd be willing to put some time into a proof of concept, if people agree that it's worthwhile and they would use it.
Any thoughts? ...Stan
P.S. Other areas that could be maintained this way:
Welcome information workspace on download images. Known problems. (Examples of class use) ... -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
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-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
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-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Em 31/12/2009 15:09, Stéphane Ducasse < stephane.ducasse@inria.fr > escreveu:
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:
+--------+-------+-------+ | Image | update|missing| | | |comment| +--------+-------+-------+ |1.0-dev | 10502 | 1831 | +--------+-------+-------+ |1.1-core| 11098 | 703 | +--------+-------+-------+ | 1.1-dev| 11098 | 1795 | +--------+-------+-------+
- pick one aweek 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.
HTH -- Cesar Rabak
csrabak wrote:
Em 31/12/2009 15:09, Stéphane Ducasse < stephane.ducasse@inria.fr > escreveu:
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:
+--------+-------+-------+ | Image | update|missing| | | |comment| +--------+-------+-------+ |1.0-dev | 10502 | 1831 | +--------+-------+-------+ |1.1-core| 11098 | 703 | +--------+-------+-------+ | 1.1-dev| 11098 | 1795 | +--------+-------+-------+
- pick one aweek 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.
HTH
-- Cesar Rabak
for info, I ran code critics on Lukas's quasi-release http://www.seaside.st/distributions/Seaside-3.0a5.app.zip which is essentially web dev without O2 I believe. (Code critics I can't get to work in web dev) Taking out spelling, there are about 30000 items flagged, of which 4802 long methods. In an ideal world, it would be nice if the whole image passed code critics.
- pick one aweek and via the mailing-list make it better and after - we integrate it.
Well the one that's entertaining me at the moment is JSObject, but I imagine people would rather start with a core class?. ...Stan -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
Em 31/12/2009 16:07, Stan Shepherd < stan.shepherd414@gmail.com > escreveu:
csrabak wrote:
[snipped]
for info, I ran code critics on Lukas's quasi-release http://www.seaside.st/distributions/Seaside-3.0a5.app.zip which is essentially web dev without O2 I believe. (Code critics I can't get to work in web dev) Taking out spelling, there are about 30000 items flagged, of which 4802 long methods. In an ideal world, it would be nice if the whole image passed code critics.
I think that for starters we should put efforts in having this state of "cleanness" in the core image first!
- pick one aweek and via the mailing-list make it better and - after we integrate it. Well the one that's entertaining me at the moment is JSObject, but I imagine people would rather start with a core class?.
Stan, Notwithstanding the truth of you assertion, I maintain that every effort it the right direction is a worthy contribution! -- Cesar Rabak
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-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
_______________________________________________ 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
my main message is Just Do Something take 10 min and do something easy Stan I would like to have already the first level of SmallLint ok - bug After the problems is that we should annotate the methods or keep a data structure somewhere to flag the false positives.
Stéphane Ducasse wrote:
my main message is Just Do Something take 10 min and do something easy
Stan I would like to have already the first level of SmallLint ok - bug
After the problems is that we should annotate the methods or keep a data structure somewhere to flag the false positives.
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
I have been 'overriding' the false positives with pragmas, as implemented by Lukas. Works well, although it would be good if they had a separate area so they don't become bigger than the code itself. ...Stan -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-knowl... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
I have been 'overriding' the false positives with pragmas, as implemented by Lukas. Works well, although it would be good if they had a separate area so they don't become bigger than the code itself.
yes this is the problem metadata. Stef
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
+1 Em 31/12/2009 16:30, Adrian Lienhard < adi@netstyle.ch > escreveu: 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
Adrian Lienhard <adi@...> writes:
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...
That gave me an idea, what about structuring that wiki like the discussion pages of wikipedia? That is, the wiki is structured by classes and methods, and in the image the browser shows a [wiki] button for classes and methods everywhere. This decouples publishing of code (functional contributions that you want to have double checked and tested by a core member) from publishing of comments (where like on wikipedia everyone can contribute without much harm). Also no dull work required to review and brush up all the information. Of course, initial effort is setting up a wiki with URLs of form /wiki/classname/methodname and including a button in OB that opens the wiki. --AA
This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE. Bill -----Original Message----- From: pharo-project-bounces@lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Adrian Kuhn Sent: Thursday, December 31, 2009 10:17 PM To: pharo-project@lists.gforge.inria.fr Subject: Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse. Adrian Lienhard <adi@...> writes:
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...
That gave me an idea, what about structuring that wiki like the discussion pages of wikipedia? That is, the wiki is structured by classes and methods, and in the image the browser shows a [wiki] button for classes and methods everywhere. This decouples publishing of code (functional contributions that you want to have double checked and tested by a core member) from publishing of comments (where like on wikipedia everyone can contribute without much harm). Also no dull work required to review and brush up all the information. Of course, initial effort is setting up a wiki with URLs of form /wiki/classname/methodname and including a button in OB that opens the wiki. --AA _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Schwab,Wilhelm K <bschwab@...> writes:
This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE.
My (general) problem with book chapters is that they are not googlable. For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes! --AA
Fair enough, but PBE is well on its way to being good enough that people will refer to it early and often. The day might come when things will be found in its index rather than a search engine. Speaking of that, how about an html copy of PBE's index (or even the entire book) on the web??? I prefer the PDF for most things, but web-hosted html would cover the search engine users. Bill -----Original Message----- From: pharo-project-bounces@lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Adrian Kuhn Sent: Friday, January 01, 2010 12:47 AM To: pharo-project@lists.gforge.inria.fr Subject: Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse. Schwab,Wilhelm K <bschwab@...> writes:
This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE.
My (general) problem with book chapters is that they are not googlable. For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes! --AA _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
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
11131 ----- - Added Class comments to FontChooser and FontChooserMorph Reorganized the class categories. Remove the as yet unclassified categories. I'm quite that a lot of it requires a little amount of energy from each of us. Stef
Adrian, This is a problem of simple solution: volunteer to convert the LaTeX PBE book to HTML and find a place to host it! my 0.019999... -- Cesar Rabak Em 01/01/2010 03:47, Adrian Kuhn < akuhn@iam.unibe.ch > escreveu: Schwab,Wilhelm K writes:
This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE.
My (general) problem with book chapters is that they are not googlable. For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes! --AA _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
what would be better is to use an infrastructure similar to the one of http://book.seaside.st (port pdf or latex into pier syntax - lukas has a bunch of scripts) since we can generate pdf from it. But this is not me that will do it (but I would support and encourage people to do it). Stef On Jan 1, 2010, at 9:16 PM, csrabak@bol.com.br wrote:
Adrian,
This is a problem of simple solution: volunteer to convert the LaTeX PBE book to HTML and find a place to host it!
my 0.019999...
-- Cesar Rabak
Em 01/01/2010 03:47, Adrian Kuhn < akuhn@iam.unibe.ch > escreveu:
Schwab,Wilhelm K writes:
This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE.
My (general) problem with book chapters is that they are not googlable.
For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes!
--AA
_______________________________________________ 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
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
I have written a web based documentation browser for me here: http://www.squeaksource.com/SimpleWebDoc.html (screenshots: http://picasaweb.google.com/laurent.laffont/Simplewebdoc ) and I'm currently learning morphic to do something similar in a browser. Is your code on squeaksource ? Happy new year ! Laurent Laffont
laurent my code was too little to be of any interest. Now the examples illustrating the TreeMorphTreeMorph class show one possible direction On Jan 2, 2010, at 9:55 AM, laurent laffont wrote:
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
I have written a web based documentation browser for me here: http://www.squeaksource.com/SimpleWebDoc.html (screenshots: http://picasaweb.google.com/laurent.laffont/Simplewebdoc ) and I'm currently learning morphic to do something similar in a browser. Is your code on squeaksource ?
Happy new year !
Laurent Laffont _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
participants (9)
-
Adrian Kuhn -
Adrian Lienhard -
csrabak＠bol.com.br -
Janko Mivšek -
laurent laffont -
Lukas Renggli -
Schwab,Wilhelm K -
Stan Shepherd -
Stéphane Ducasse