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.
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...
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.
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.
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.
> 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.
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.
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?
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.
How in the world does "being compliant to authority" contribute to university success? What major emphasizes compliance over learning the material and doing the work?
You say, "I already know this stuff, can I just take the final?"
Uni says, "Yes, you can test out of it and get credit for the class."
I was allowed to take the final for any class I wanted to and if I passed I would get the grade I got on the test. I thought this was pretty standard as I've seen it at multiple universities.
Yeah. I can't help but wonder if the parent went to a school that charges a set amount of tuition regardless of how many hours you take (with the exception of part-time versus full-time). My alma mater does that, and I was offered to take finals if I thought I already knew the material as well. Though it was just for credit, not grades; basically the equivalent of passing an AP test for that subject.
I don't see anything in your response about success.
It's true that if you want credit for completing a major, then it is necessary for you to actually complete the major, but that still doesn't equate to graduating at or near the top of your class.
Eh, I do see his point though. I've been in a similar situation myself due to a transfer once in the past where, due to university requirements, I had to take a module that I was uh, "overqualified" for to fulfill major requirements.
I don't quite agree with his overall conclusion that university education is pure compliance off of this one gripe though. Moreover, I do believe that many universities allow you to bypass certain module via a test / some other demonstration.
I completed all of the courses for the major, with the exception of CS101, introduction to computer programming. I took many classes that ostensibly had a prerequisite on CS101, including additional nonrequired courses that could have easily been substituted for CS101. Nonetheless, as you say, it was "necessary for [me] to actually complete the major" by going back after taking CS4xx to complete CS101. Was this a required part of the major? yes. Was it a valuable part to be required without exception? Maybe, but I tend to not think so.
> I don't see anything in your response about success
"Not graduating" is a pretty clear way in my mind to "not succeed." I indicated that compliance to authority in my experience was necessary for graduation, which implies that it was necessary for success, does it not?
Completing assignments and tasks that are not about learning, as they are about compliance. Examples: attending class (big one), repetitive assignments, pointless assignments where learning is minimal but tedium is maximized.
How do you get started with GUI programming? I can't seem to find anything on this for Pharo6...and barely anything for earlier versions (which I'm assuming are now obsolete).
I believe it. If he owns everything free and clear--I'm betting he does--and he avoids big purchases and fancy trips, he can basically get by on purchasing nothing but food, electricity, phone, and gas. Tack on some clothes and reasonable eating out, and you can live well on $25,000 per year. Everything else was probably paid for by the team.
What's the explanation for the huge drop in sales? Those single engine airplanes are still around? Deregulation of the airlines has resulted in cheaper commercial air travel? More telecommuting? What?
There was a terrible "aviation winter" in the mid-80s with product liability concerns, economic issues (high interest rates), and a spike in fuel prices resulting in the bankruptcy of several manufacturers and other manufacturers stopping the manufacture of piston-powered airplanes entirely.
To me, the more interesting question is "why were the 60s and 70s so good for GA?" De-regulation of airlines was probably one factor, but it can't be the only one.
I'm 45 and a pretty avid owner and pilot. For most airport activities (fly-ins, safety seminars, etc), I'm usually the youngest one in the room, often by a lot. I get the sense that wouldn't have been the case 50 years ago.
> To me, the more interesting question is "why were the 60s and 70s so good for GA?" De-regulation of airlines was probably one factor, but it can't be the only one.
Lots of WW2 pilots still alive and interested in flying in the 60s and 70s, maybe? I'm just speculating, but the population of flight-trained people in the country has probably not been higher than then.
I know a lot of veterans got pilot's certificates with the GI Bill education benefit, so that was probably part of it (in addition to conversion of military pilot experience into civilian certificates)
RE your last paragraph, I think cost is a HUGE factor preventing more young GA pilots. What's the cost to get a PPL these days? In the range of $5000-10000? And IIRC, the total operating cost per flight hour, even for something like a C-172, is north of $100?
Even as a young 30s software engineer with a comfortable salary and a PPL on my bucket list, it looks like a terrifyingly expensive hobby. The vast majority of people simply can't afford it.
Local flight school rents their 172s for $135-150 (depending on airplane), and based on my ownership experience, they're not making fat margins on that.
Very good question. Planes used to be so much cheaper, too.
I'm not an expert, but from what I gather there was this issue where product liability law suits drove aircraft manufacturers out of business. Even Cessna went bankrupt and was sold to Textron, and production of even the Cessna 172 stopped for a decade or so in the mid 80's.
The General Aviation Revitalization Act was supposed to fix this, not sure how much it has (see link at end).
Would love to hear more about this. Regulation is clearly a huge factor.
By the way, as much as one can complain about the general aviation scene in the USA (regulation, FAA, ...), on a global level it's still paradise. In Europe it's more complicated and expensive and cumbersome, even though the EASA is slowly moving in the right direction as far as I can tell. In Asia, general aviation is nearly unheard of. Australia has some, though it's really too big :-) Interestingly, Africa has pockets, e.g. in the south (South Africa, Namibia) and east (Kenya).
I have no expertise here, so this is just speculation. But I am thinking that it got to a point where everyone who wanted and could afford a small plane had one, they could be kept flying forever, and there weren't any major improvements so no reason to buy a new one. Plus, as a comment above said, small planes used to start with a military contract, and the military was switching to jets so you didn't see that anymore.
