Thanks, I'll make those changes.

One other thing I was thinking might be valuable is a section on distribution? One thing I notice a lot is people not considering cross-OS compatibility or packaging until they're completely finished with a project, at which point they fire up pyinstaller, a bunch of things don't work (e.g. reading asset files), they try and fail to fix them, and then get frustrated and give up.

It might be nice to suggest some things like:

• using relative paths to reference all asset files
• using os.path / pathlib to keep filepaths os-independent
• (trying to) explain the quirks of pyinstaller --onefile mode

And maybe some other stuff like that?

There definitely could be a section about paths. I would recommend relative paths with the slashes like this ->"/". That will work on all operating systems. I frequently see newbies who have heard to use os.path.join, but do end up doing something completely useless with it, and since it isn't actually necessary, I think we shouldn't bring it up here.

PyInstaller is a bit more advanced, and it's something that needs a lot of explanation, so maybe it shouldn't be in the newbie guide either.

If we're brainstorming ideas for sections, it could be good to have some "hello world" code. I remember when I was learning pygame I found the game loop on some random website, and it really helped me. I also see people who don't knowClock exists, or who don't understand they have toflip(), or who just don't understand a basic pygame loop.

This is my personal brand of minimum viable pygame program:

importpygamepygame.init()screen=pygame.display.set_mode((1280,720))clock=pygame.time.Clock()whileTrue:screen.fill("purple")foreventinpygame.event.get():ifevent.type==pygame.QUIT:pygame.quit()raiseSystemExitpygame.display.flip()clock.tick(144)#framerate

Line 22, supported OS comment: What even is BeOS?

Has anybody tried compiling on Haiku?

Has anybody tried compiling on Haiku?

Let's keep it simple for the newbies guide.

I added a new section about software architecture and design patterns, which I think fits really nicely in this and gives a good opportunity to talk about the pygame "base template" and game loops in general in a more abstract way. Also made most of the suggested changes from comments - all that's left now (I think) is:

• removing mention of SDL / multiple windows limitations (missed that one~)
• linking function calls to docs
• running setup.py docs to make sure it all looks right
  And I decided to just add a sentence to the 'learn python' section about paths, rather than adding a standalone section. I agree that distribution is probably too complex for this.

Has anybody tried compiling on Haiku?

Let's keep it simple for the newbies guide.

I'll make this its own issue then. I have no idea how well current Pygame runs on FreeBSD or Haiku.

Alrighty, I've made another update, which should address those few remaining issues I mentioned on the last diff and fix the HTML formatting issues (of which there were many).

Now that I think about it, a lot of perf advice like "avoid quadratic collision detection" or "don't use scrolling backgrounds to keep blits low" is situational, and the most important advice is "please benchmark instead of blindly guessing" and "move loading and rendering out of the game loop if you can".

Alright, I’d like this to move forward, since it is a needed modernization, so I talked to illume about how to get this ready to go.

The biggest sticking point is dirty rect optimization, illume says it’s still valid in some cases, and doesn’t want it presented as old advice. I think that it should be contextualized as an advanced technique, because beginners often mess it up when they try to do it.

Additionally, it was brought up in that the stuff about HWSURFACE doesn’t particularly belong in a newbies guide. I personally like the way Ghast put it in, but if we’re changing dirty rect that section might just go.

Maybe the dirty rect stuff could be more of a footnote in a performance section, that expands more on profiling.

I think illume and I both have an idea or two about how to get this fully up to par and merged, so either of us might take it over. But I’m also happy to leave it to Ghast, with those notes.

Feel free to take this over - it seems like you two have slightly different visions for this guide than I do so I'm probably not the best person to write up those ideas. I've also never personally used (or seen anyone use) dirty-rect optimization so my insight on that is limited. I hope my attempt at this was helpful at least though!

Updated the title to indicate that this needs taking over. I think some good progress was made here but it needs somebody argumentative to get it over the line :)

If you want to take this over, either close this PR when you open a new one - or let me know that you want to take it over and I will close it.

Also: Please credit the author of this PR in your takeover PR.

I will have a go at taking this over.