On Tue, Oct 10, 2017 at 3:58 PM, horrido <horrido.hobb...@gmail.com> wrote: > Interestingly, I'm getting a fair amount of pushback on this. Personally, I > think it would be very helpful to have a live (updatable, so as to keep it > current) reference page for the class library, something that developers can > easily look up what they need. After all, most of the power of Pharo comes > from the class library and we need to make it as accessible as possible to > less experienced Pharoers (i.e., beginners).
This is why I started to comment even the classes that we all know You see having a lovely comment on Association, Array, OrderedCollection with all the love we can is the best welcoming. > > Exploring the class library through the System Browser is very inefficient. > This is further exacerbated by the fact that many classes and methods are > simply not well-documented (containing a cursory remark which is just barely > useful). Totally agree. Now the good aspect is that ANY pharoers can help making such class/method comments great. It takes 5 to 10 min. And I started to add executable examples " 3 + 2 >>> 5 " > I realize that creating a live reference page is not easy to do. In fact, > it's a lot of work. But the absence of such a page is a real obstacle to > Pharo acceptance. In the past we generate a javadoc but nobody looked at it. > > > > horrido wrote >> Thanks. I gave your answer verbatim. I also added the following paragraph: >> >> The problem I find with today’s developers is that they are rather >> closed-minded. They are rigid and inflexible, and not willing to adapt to >> new and different ways of doing things. In my generation (circa >> 1980–1990), >> people didn’t have a problem with trying different technologies. That’s >> why >> I had no issue with learning Smalltalk 10 years ago, after I had retired >> from a 20-year-long career in C systems programming and FORTRAN scientific >> programming. >> >> >> >> Sven Van Caekenberghe-2 wrote >>>> On 6 Oct 2017, at 14:54, horrido < >> >>> horrido.hobbies@ >> >>> > wrote: >>>> >>>> I received this comment from someone who complained: >>>> >>>> *What about the lack of documentation? From time to time I’ve checked >>>> some >>>> SmallTalk implementations like Squeak, GNU-Smalltalk and now Pharo. Of >>>> these, only GNU-SmallTalk appears to have a free, official programming >>>> guide >>>> and core library reference that any serious programmer expects from a >>>> language. >>>> >>>> https://www.gnu.org/software/smalltalk/manual-base/html_node/* >>>> >>>> I pointed to Pharo's documentation but then he came back with: >>>> >>>> *Then show me a link of the free, maintained reference documentation for >>>> the >>>> classes that form “the core library”, like this one for Python >>>> (https://docs.python.org/3/library/index.html)* >>>> >>>> It's true, most Smalltalks do not have a core library reference, not >>>> even >>>> VisualWorks! So what is the proper response to this complaint? >>> >>> The first answer is that Pharo/Smalltalk is unique in that a running >>> system/IDE contains _all_ source code, _all_ documentation (class, >>> method, >>> help, tutorial), _all_ unit tests and _all_ runnable examples in a very >>> easy, accessible way. It takes some getting used to, but this is actually >>> better and much more powerful than any alternative. >>> >>> The second answer is that there are lots of books and articles that take >>> the classic/structured book/paper approach. There is >>> http://books.pharo.org, http://themoosebook.org, >>> http://book.seaside.st/book, http://medium.com/concerning-pharo and many >>> more. >>> >>>> Thanks. >>>> >>>> >>>> >>>> -- >>>> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html >>>> >> >> >> >> >> >> -- >> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html > > > > > > -- > Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html >
