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