Thomas I suggest you not to stress. Did you see the introduction of FileSystem? We did it perfect and you get a documentation.
So focus on what you want to do and do not stress about the rest. I can tell you that we know what we are doing and we certainly care more about the system that many other people. Pharo systematically improves and its documentation too. Now if you have a couple of hundred of thousand of dollars we can fix such situation fast, else it will just get slowler. Stef > 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 >
