On Thu, 04 Apr 2013 19:25:35 +0100, Sven Van Caekenberghe <[email protected]>
wrote:
On 04 Apr 2013, at 20:21, Marcus Denker <[email protected]> wrote:
On Apr 4, 2013, at 8:15 PM, Paul Davidowitz <[email protected]>
wrote:
To Camillo Bruni:
I'm not using any slot image (I only looked over the paper). According
to the Pharo book, 'pvt' should be implemented in the mainstream image.
The Pharo book is about a version of Pharo from many years ago.
To Marcus Denker:
There are actually several methods in the image with the 'pvt' prefix.
Please update the doc (Pharo book) to remove talking about 'pvt'. It
would have saved me a little headache :)
The pharo book is very old… yes, we need to update it. What should I not
do to have time for that?
Marcus
Documentation, of any kind, always comes back to haunt you.
This is a real problem, even a class or method comments quickly gets out
of sync as software evolves.
Maybe, just like in code, the key is to write as little as possible in
an elegant non repetitive way.
That's fine if you never want to have new people pick up your project and
get started. Otherwise I would say that an undocumented API may as well
never have been built. Look at Morphic. That's about all you can do with
it if you've got a full time job that's not Smalltalk related - look at
it. The documentation is about zilch and what there is consists of layers
and layers of material relating to varying systems of varying ages.
The answer to Marcus' question "what should I not do to have time for
that" is "anything". Nothing is more important than accurate
documentation. Even a system that is broken will get fixed quicker if
there is documentation which allows new hands to be added to the task of
fixing it.
Incorrect documentation is WORSE than no documentation; would anyone
really suggest that Pharo would be a viable system without any
documentation?
My experience of several large Open Source projects (and many Closed
Source ones) is that the people involved in the projects get familiar with
the APIs and methods and can fail to see just how hard it has become for
outsiders to break in.
This is why I'm worried about slots. At the moment I can at least learn
about Smalltalk generically and pick up Pharo and, with a lot of effort,
get to the point that I can do something useful. If new concepts are added
to the language *and then used by the in-group to get on with the things
they're interested in* without good documentation then all that has
happened is that the tool has become more specialized for the work of the
contributing group while becoming harder to access for others.
I'm *not* really that worried about slots in and of themselves if they can
be added cleanly; I'm more worried about the gap between what
documentation there is and how the system *actually* works growing ever
wider.
I'm also not attempting to say that those who are very active with Pharo
are bad programmers because documentation has become problematical - if
they are then I'm a bad programmer too - I just want to point out that a
system has even more need of documentation than a completed application
and *if it's possible* (and I know that finance is an issue in the real
world) then I think that updating the Pharo book(s) to a point where they
describe the current Pharo 2.0 state is FAR more important than work on
Pharo 3.0.
Well, that's my view, anyway as a professional programmer who has
struggled to get to grips with Pharo in my spare time.
Thomas Worthington
