quick comments about getting started doc

elliewix commented 5 years ago

Hi! Per request from the python educators slack, I took a quick pass through the getting started guide. It's a really good framework! Here's some initial things to ponder, with much of this being completely normal stuff that I see happening in all first drafts of this stuff. These are really quick notes, so my language is pretty terse.

add sections for experience expectations, with links as well to other tutorials if they need that. Specifically state that installation instructions expect that you can install python, open up a prompt, and execute command line directions.
Add specific recommendations for how windows users should run bash commands, or have separate commands for them. If some of these commands will only work in specific windows versions or apps, say that. (you sort of do this later, but if you are presuming that they are to use gitbash or something else, state that. I'm a mac user so maybe these are totally fine!)
have a specific header for installation instructions
be clear about which elements of the example copy/paste stuff the user should alter. path/to/my_game is a clear placeholder to very experienced people, but (like foo) many people will think it's a serious thing. You sort of state that my_game should be changed, but you only state my_game and don't reference the full path you have in the example. Also make my_game inline code in the text. An easier way to do this would tell them to navigate within their shell into a folder they'd like to store their project folder in. Then have the mkdir directions. So breaking it apart into two separate directions.
by other you mean macs and linux? if that's true, can you state that?
add a subheader that separates installation vs now we're doing python
the block after "note that ppb.run has a new parameter:" isn't clear if they should add this code, if this is informaitonal, or if they should replace all code with this stuff.
"At this point, if you have a png on your computer, you can move it into your project folder and call it player.png" has some confusing hedges in it.
this code also presumes that they have some level of understanding of python custom classes and methods. I suggest that you provide a suggested chapter or something for anyone needing to brush up.
eventually screen shots would be really helpful, but not worth the fight at this level of draft.
also state if the name main is really required or just convention.
you don't state how to run the script, which you might be presuming, but people may not know how to run a script on the command line.
I suggest that you have a final copy of the full code somewhere so people can check that they did the things right.

Also when I tried to follow the directions I got this:

wirelessprv-10-193-173-45:pbb_test wickes1$ python3 -m venv .venv
Error: Command '['/Users/wickes1/Documents/pbb_test/.venv/bin/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1

I used a conda env and it worked that way. However, the final thing just has the window open and close, and the sprite doesn't appear to move.

Here's my traceback:

pygame 1.9.6
Hello from the pygame community. https://www.pygame.org/contribute.html
Traceback (most recent call last):
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/events.py", line 76, in __event__
    meth(bag, fire_event)
TypeError: on_update() takes 2 positional arguments but 3 were given

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/wickes1/Documents/pbb_test/main.py", line 11, in <module>
    ppb.run(setup = setup)
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/__init__.py", line 34, in run
    eng.run()
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/engine.py", line 79, in run
    self.main_loop()
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/engine.py", line 93, in main_loop
    self.publish()
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/engine.py", line 121, in publish
    game_object.__event__(event, self.signal)
  File "/Users/wickes1/anaconda/envs/py3pbb/lib/python3.7/site-packages/ppb/events.py", line 83, in __event__
    raise BadEventHandlerException(self, meth_name, bag) from ex
ppb.events.BadEventHandlerException: 
Player.on_update() signature incorrect, it should accept an Update object and a signal function.

Update is a dataclass that represents an event. Its attributes 
tell you about the event.

The signal function is a function you can call that accepts an event instance
as its only parameter. Call it to add an event to the queue. You don't have to
use it, but it is a mandatory argument provided by ppb.

It should look like this:

def on_update(update_event: Update, signal_function):
    (Your code goes here.)