Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
23 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stan Shepherd
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)
...
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stéphane Ducasse
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-knowledge-Knowledge-reuse-tp4236694p4236694.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

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









Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stéphane Ducasse
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
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

csrabak

 

Em 31/12/2009 15:09, Stéphane Ducasse < [hidden email] > 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

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

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

Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Adrian Lienhard
In reply to this post by Stéphane Ducasse
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
>> [hidden email]
>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stéphane Ducasse
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Janko Mivšek
In reply to this post by Adrian Lienhard
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

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stan Shepherd
In reply to this post by Stéphane Ducasse

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
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

csrabak
In reply to this post by Stan Shepherd
Em 31/12/2009 16:07, Stan Shepherd < [hidden email] > 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

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

csrabak
In reply to this post by Adrian Lienhard
+1
 

Em 31/12/2009 16:30, Adrian Lienhard < [hidden email] > 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


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stéphane Ducasse
In reply to this post by Stan Shepherd
>
> 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
_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Adrian Kuhn
In reply to this post by Adrian Lienhard
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Schwab,Wilhelm K
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: [hidden email] [mailto:[hidden email]] On Behalf Of Adrian Kuhn
Sent: Thursday, December 31, 2009 10:17 PM
To: [hidden email]
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Adrian Kuhn
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Schwab,Wilhelm K
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: [hidden email] [mailto:[hidden email]] On Behalf Of Adrian Kuhn
Sent: Friday, January 01, 2010 12:47 AM
To: [hidden email]
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Lukas Renggli
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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

[update 1.1] #11131 Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

Stéphane Ducasse
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
_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

csrabak
In reply to this post by Adrian Kuhn
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 < [hidden email] > 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
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
12