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
