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

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

> 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

> 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