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
> [email protected]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
_______________________________________________
Pharo-project mailing list
[email protected]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
