[claystu]

TLDR: Pharo needs mountains of high-quality documentation equal to Python's docs or Java's docs if it seriously hopes to attract server-side or desktop mindshare among developers.

Long Version:

In 1980, Smalltalk had some of the best documentation of any language out there. In 2019, it basically has none. By 2019 standards, Pharo 7 ships without any documentation at all. That's a game-stopper.

Pharo 7 looks really polished. It sounds like the design team put in tons of hard work over the past year and half to produce this release. Moreover, since it's smalltalk, Pharo is also probably very powerful for both web and desktop development. BUT NONE OF THAT MATTERS IF DEVELOPERS CAN'T FIGURE OUT HOW TO USE IT!!!

(pardon the all caps, but I want to emphasize my point)

Here is my message for the development team: if you really want developers to start building stuff with Pharo, then you absolutely must (1) write detailed, soup-to-nuts, high quality docs for web design and (2) write another set of detailed, soup-to-nuts, high quality docs for desktop GUI programming.

The Pharo book doesn't cut it--not even close. It's not a very good book. The Pharo MOOC doesn't cut it--again, not even close. Who wants to learn that way? ProfStef is just a fancy hello world; it's really not a tutorial and it doesn't lead anywhere.

I realize that what I'm saying comes across as pretty strong medicine, but please understand, that's because I actually think Pharo looks amazing and would like to use it.

In my opinion, you should stop development on Pharo and document what you've built instead. Write docs for a year. Today's release announcement states that the Pharo 7 team closed 2142 issues. Brag in 2020 about the fact that you wrote 2142 pages of documentation and tutorials over the past year. Make your documentation coverage as thorough as your testing coverage.

Imagine what might happen if Smalltalk 2020 was as thoroughly documented as Smalltalk 80.

[klibertp]

I support the whole of your post wholeheartedly.

Just wanted to add, there's quite a lot of documentation in the form of class and method comments, which could be (a starting point for) reference docs if dumped to (even static) HTML. The fact that I can't read about the methods of Collection class in the browser, like I can do here: https://docs.python.org/3/tutorial/datastructures.html or here: https://docs.racket-lang.org/reference/pairs.html?q=list#%28... or https://ruby-doc.org/core-2.6/Enumerable.html (or basically with any other lang) in 2019 is very wrong in my opinion :(

Even after I run the image, the browser doesn't make for the best tool to learn the overview of the system. Methods are tiny and a lot of them and you must click each one in turn to see the docstring. It's not easy to know which class is in which package or why. A lot of the classes have no docstring, but are described in some the ancestor class, and there's no way to display dosctrings of a group of classes at once - instead, you have to click through them manually. Various search tools help, but it's also not immediately obvious where they are or how to use them.

The system gets infinitely more discoverable once you install Roassal, which has tons of very useful example visualizations. But it's not installed in the default image, you need to know you need it and know enough Smalltalk and Pharo to install and run it and then how to modify the examples to make them useful for your current exploration area.

Anyway, that's how it is: painful to learn. It's great if you have someone to take you through the whole thing, but that doesn't scale, while the rate of change renders non-reference-like docs (Pharo by Example, Deep into Pharo) obsolete very quickly. Putting Pharo-devs effort into actually documenting the classes and then exposing these docs in accessible HTML is something I would really love to see one day...

[offray]

Thanks for the feedback.

Have you seen [1] and specifically [2]?

[1] https://pharo.org/documentation

[2] http://books.pharo.org/

Do you have a particular example of a site where the kind of documentation that you would like to find is published for other language (lets say Python)? This could help to understand better which are the expectations and why current books and MOOC are not enough.

[khinsen]

From my experience as a recent Pharo user (started in October 2018 with the Pharo MOOC), the two main issues with existing documentation are

1) Much of it is outdated. 2) Much of it supposes significant prior knowledge of Pharo.

Once you start to become familiar with Pharo, neither is much of a problem. You see that the screenshot of Pharo 5 resembles what you see on Pharo 7 in spite of superficial differences. And you picked up enough of the jargon to be able to judge if some documentation is close to your level or not.

For someone who downloads Pharo 7, starts it up, and wonders "what now", most of the existing documentation is confusing. The MOOC was a much better starting point back in October, but with the new system browser in Pharo 7, it's seriously outdated as well.

[hilaire]

Racket is very exemplary with its documentation: https://docs.racket-lang.org/

GUI documentation will likely never show up: the current graphic framework is outdated, subject to deprecation and no subject to improvement since Athens low level layer was left as it is. It may or may not be replaced by Bloc or something else. I don't thing anyone is willing to write documentation when there is not clear direction regarding the GUI framework.

[klibertp]

> when there is not clear direction regarding the GUI framework.

Isn't it crazy for this not to be solved yet?! That's a long time - don't remember exactly, but I started with Pharo 1.4 IIRC, and it was bad back there already, then juz got worse.

Is there a blog post detailing a) all the kinds of GUI frameworks that are out there and how advanced their development; and b) what approaches were tried and abandoned, when, and why? I know it's much to ask, but, at this point, I feel the lack of progress in this area should become a much higher priority, and a blog post like would help in recruiting people for the effort.

[claystu]

Let me take these in reverse order...

Here is a link to Python's docs(https://docs.python.org/3/). It's still a little busy, but you can go a long way just by using the Python Tutorial (helpfully subtitled with 'start here') followed by the full Library Reference. A lot of people rave about how great Python is and how popular it's become, but I think one of the unsung heroes of Python's success has been the great documentation.

A (fairly) recent language that appears to have taken a page from Python's documentation success is Google Go. Here's the Go Docs:(https://golang.org/doc/) Take a look at that page. It describes Go, then tells you how to install it, then provides a pretty good tutorial (called a Tour of Go), and then provides a really comprehensive Reference Manual that tells you the various libraries Go ships with, which includes a hyperlink that reveals documentation for each library, and if you explore the linked page and click on a function, that's also a hyperlink that takes you to the actual code for that function so you can read the source code--itself is written in Go. Basically, it's easy to see how Go works, find out what libraries it includes, read good docs for each library, and even explore the library's implementation.

Continuing my argument, I would propose that many of the widely adopted languages of today aren't just good languages, but also benefitted from really good documentation. K&R is still famous, even though the last edition came out in 1989. Here's an interesting question: does C become such a big hit without the fantastic books it had? In the pre-WorldWideWeb universe in which C came to fruition, great books were critical. I would argue no. I believe it's documentation was a critical element of its success.

I think Perl has a similar story. Yes, it was powerful and useful and that was a big feather in its cap, but it also had amazing documentation in the form of books(Camel Book, Llama Book, O'Reilly Perl books in general) and man pages. It's easy to forget--and some don't even know about--the amazing man pages that Perl enjoyed. Here's a hyperlink to Perl's Man Pages table of contents: (http://perldoc.perl.org/perl.html) They are awesome! For example, check out the Perl regex tutorial man page: (http://perldoc.perl.org/perlretut.html) To this day, that's still probably the best explanation of regexes out there. And if that's too much, you can read Perl's quick and dirty regexes man page instead:(http://perldoc.perl.org/perlrequick.html) There's man pages for so much in Perl it's ridiculous.

(Rough waters ahead...)

Now back to your first question about Pharo's current docs. Here was my experience...

I checked out the links you posted. After a few clicks, I got a page with a bunch of pictures that looked like books. I'm wasn't sure what book I should pick, but "Pharo By Example," seemed promising. I clicked on it and discovered it's a PDF--not the preferred format for the web--that tells me the current version of Pharo is still Pharo 5. So I'm already worried because the book is out of date.

OK, I move forward to page 16 before I get to hello world. That's not too bad for a book, but slower than lots of web based tutorials, which is the real competition for "Pharo By Example" since I'm reading it on the web. Page after page then scroll by about Pharo the IDE, but not Pharo the language, which is what I'm really trying to learn about. Finally, on page 28, the book says we get to learn how to define a method, which is apparently how we do anything in Pharo, but then we crash to a stop and write a test first! Then we move forward again until we, at last, get our second piece of code: shout ^ self asUppercase,'!'

That extremely short method doesn't arrive until page 31.

Next we move to Chapter 3 and make a GUI game called LightsOut, which sounds cool, but it's like drinking from a fire hose because none of the syntax or libraries have been explained yet. (Note: At this point, I don't feel like I could run with this example to make games of my own.) If you survive Chapter 3, which is doubtful, and make it to Chapter 4 on page 59, the book finally explains Smalltalk syntax, though even this seems a bit jumbled since the real discussion of message syntax, which is at the core of Smalltalk syntax, is pushed back to Chapter 5 for some reason. Control structures are discussed in Chapter 4 instead. To put that into perspective, there's a mention of blocks serving as lexical closures in Chapter 4 before we really find out how basic messages work in Chapter 5.

By the end of Chapter 6, we've covered the Smalltalk object model and I still have no idea how to actually make a program! At least, I don't think I do.

To put it bluntly, "Pharo By Example" isn't a good programming book. Yes, I recognize it's a labor of love. Yes, I recognize that it's being given away for free. Yes, it took time to write. That's all noble. But it doesn't change the basic, ugly fact: "Pharo By Example" fails to get the job done.

At this point, I'm not at all confident that I will be able to program in Smalltalk after reading this book. More importantly, the book hasn't provided any real reason to become a Smalltalk programmer. It all looks a lot like IDE customization and tools for a language that doesn't seem to run anywhere except in the IDE itself. As an emacs user, I've already got one of those... :)

Seriously, I think some real thought needs to be put into explaining (1) why anyone would benefit from Smalltalk instead of more mainstream language and (2) how to showcase Smalltalk's strengths without getting lost in the weeds of the IDE.

Here's the curriculum that I suggest: (1) tell us how to download, install, and run Pharo (2) demonstrate how to build a few old school IO games--HiLO, Hammurapi, Trek, etc...--so we see how you can do IO. Along the way, introduce Pharo's syntax (3) give a full, long-winded, boring as hell discussion combining and improving upon Chapters 4-6 where you admit up front that it's going to be boring as hell and then (4) go back to saving stuff to Github and distributing the software. (5) explore the various parts of the IDE in independent chapters while providing real examples of how those features make our lives better. (6) go back and provide an entire section of webpages explaining, in great detail, the Morphic stuff that just gets a passing glance in the book for that LightsOut game. It really looks like there's something there, but who knows. That little chapter on Morphic in the back of the book doesn't remotely cut it. (7) provide separate chapters on important libraries? that Pharo comes bundled with--the kind of libraries that all modern languages take for granted and expect. (8) provide some real-world, well-commented, Pharo programs for us to dissect so we can see what they look like. For most languages, I can just download a few open source projects and read code until I'm sick of it. Does that even exist for Pharo?

Let me say again that I honestly think Pharo looks amazing. I really want to know how to make something in it, but I'm not sure I ever will because the amount of effort I'm describing is huge. I hope it happens though.

Finally, I recognize that my feedback was critical. I sincerely hope that you take it as constructive criticism rather than as an attempt to insult. The last thing I'm trying to do is insult anyone.

[scroot]

Your points about documentation are well taken. There seems to be a dissonance between the mainstream world and Pharoers in this regard. Mainstreamers pretty much expect documentation to be good and to be reliably available via the web (I expect this myself in most cases). In the mind of a Smalltalker, there's no need for a web page that lists classes, methods, and what they do because that's precisely what is available inside the image and what many of the built in tools are there to provide. Now, is that good enough? Clearly not. Outsiders might not know this is the case, especially if they are coming in completely blind.

I think it would be not too much work to parse out this kind of information (Class comments, methods and method comments, structure etc) and spit it out as a web page that could be hosted somewhere. Do you think this would help, at least somewhat, to bridge the divide with new users?

[claystu]

Your suggestion of parsing out the in-code documentation would go a long way towards documenting the libraries, provided the documentation is of high quality. However, that still doesn't address the bigger question: how do I program in Pharo.

There's a book, "On to Smalltalk" that actually did a decent job of getting you started, but it's decades out of date now.