Review onboarding docs for new users

[macta]

Now we are live with some documentation - need to review what a new user sees, and whether they are properly guided through what is there and whether a picture or screencast might help. We had the following feedback on Discord:

Just sharing an issue I had with Exercism. 

- The windows install told me to download Pharo Launcher. 
- And then it told me to install Pharo 7 32-bit version because 64-bit  has some bugs (oh-boy-here-we-go.jpeg)
- I follow the steps to download the first exercism via the playground. Find the first exercise test. and run the test.
- It says the when you run the test and it fails, it will suggest a fix for the issue. In this case, it was supposed to create a new class for me as an easy fix. 
- This is the part that didn't work for me. I couldn't figure out how to make a new class and the test was failing and not suggesting any fix for me. 
- And I think the 32 bit version of Pharo 7 ran really slow on my machine. Not sure why.

It wasn't clear if circles read the section: https://exercism.io/tracks/pharo-smalltalk/tests (and I don't think the install guide links to it)

[bencoman]

Side comment: I think the work Tim did to improve the auto-class creation is great, and its one of Pharo's super cool unique features, but after experiencing it doing the Bowling exercise as a student, I feel its a bit too foreign and overwhelming for newbies. At least the first few exercises, until students pick up the paradigm of auto-creating methods, I think we should provide empty solution classes to simplify things at the start.

In addition, I read somewhere the purpose of the Hello World exercise just to test downloading/submission, so I've been thinking we should make it super-super-easy by almost providing the whole solution like this...

HelloWorld >> sayHello
    ^ 'fix me'

>

[samWson]

I've long thought that the addition of some images of the UI would be a big help getting through the first exercise, especially with the Windows installation process. I'm not sure how easy it is to embed images in our docs in a way that the website will correctly display given how it constructs the webpages from our markdown files.

Another aid I have been thinking about is a few YouTube videos showing screen casts of the features people need to know about the IDE. The caveat here being YouTube might not be available in some countries or less than ideal network connectivity.

[macta]

@samWson - I did a quick experiment to embed images into the docs, and its pretty easy - if you look at tests.md (or browse our docs online), you can see a quick experiment I tried. The trick is to do something like the following:

## Immediate Feedback
Pharo has great support for working with tests, and incremental testing! You can run any test for an exercise by clicking on the orb next to a test case class or method.
![Browser Test Orbs](https://github.com/exercism/pharo-smalltalk/raw/master/docs/images/TestOrbs.png)

I think a sreencast would probably be even better, but maybe you can use this example to put together some better docs (my graphics skills are rather limited). But for now, everything helps.

[macta]

@bencoman - as a sidenote, I probably should have mentioned that the desire to not define classes is not just driven by a purity of TDD - its actually much harder work to provide template classes as you suggest. We need to provide sample solutions to demonstrate the viability of an exercise (and the travis script only passes if we export one) - and due to namespacing, it gets awkward to write out an alternative representation (not impossible mind you) - so it was a hell of a lot easier to just not write it... and I quite liked the idea of the one button click. I know that @circles had an issue, but he's the first one, and I think a few pictures might sort him out. But, I guess time will tell (and I'd prefer to fry bigger fish by getting namespaces working as well as the mentoring tools and auto-mentoring)

[samWson]

@macta I had a look at the images you have embedded and they are and they are just what I had in mind. By themselves I think they are a great improvement. With the skills and tools I have the only improvement I could make is a few red boxes/circles, arrows, and labels.

As for a screen cast I think it would be a great addition as some people may prefer watching video instead of reading text. It's something I've never done before but I could look into it. I'm thinking we host the video on YouTube and either link or embed the video in the docs.

Still it's a lot of extra effort where a few screen shots may suffice in the short term. Let me know what you think.

[macta]

@samWson I would say lets get some images sorted out, and raise a separate issue for a screencast (the other Stephan showed me how to use Screenflow at PharoDays 2017, and I have a copy that I used for Pharo Lambda that I could dig out - if we work out a good script). But I would wait on the screencast until we have finished the package upgrade, as it will look different)

[samWson]

I'm looking at the Installing Pharo section right now. Under Getting Started there is this text:

Underneath the classes panel there are 4 radio buttons, "Flat" (shows the classes in the package), "Hier." (shows a class hierachy), "Inst. side" (shows instance methods), "Class side" (shows class methods/constructors).

I think this section really needs a close up image as it's not obvious and even I had trouble spotting it moving from Pharo6 to Pharo7.

An image of the Pharo Launcher might be a good idea too as it's not obvious what all the controls do at first glance. A single image with some number labels and accompanying text might be in order or a few close ups images of the controls instead. I'm leaning toward single images with labels as I don't want to clutter the docs up with too many images.

Here is another one that would do well with an image of the submit menu:

All you need to do is right click on a package (in this case, the Welcome package in the top left panel), and select the Exercism|Fetch Exercise menu item. This will prompt you for an exercise name (e.g. hello-world), and will then retrieve it automatically for you.

A close up of the exercise dialogue with an exercise name in it would be good too.

I think that would cover our worst parts. The other sections look good for now.