📚 Docs: Guide - Hello World & Generative Shape Art

[dannyfritz]

📚📚📚

Benefits of a Guide:

• More approachable and friendly than code samples
• See the process of coding something. Not just the finished product.
• Common pitfalls explained and avoided
• Explanations of trade offs
• Conceptual peeks under the hood of ggez's modules for deeper understanding

Assumptions and Guidelines:

• User can write a hello world in Rust
• User hasn't done anything with ggez
• User has very little gamedev experience
• Written from the we/us perspective unless an action must betaken, then you/your is used
• Formatted with Markdown
• Written in English
• Conceptually, earlier sections should be easier and later sections should be harder
• Tone is fun, friendly, and joking
• Always link to the ggez docs when appropriate
• Include unguided challenges at the end of each guide
• Have a brief summary at the top explaining what the User can do after reading the guide

Guide Sections:

• Hello ggez! (Loop + Window + Conf)
  • Prerequisites
  • Loop
  • Window / Conf
• Generative Art (Shapes)

For another PR

• Overview
  • What is ggez?
  • How is it different than X?
• Mouse Tail (Mouse)
• Menu (Text)
• Guessing Game (Keyboard)
• Image Viewer (Image)
• Music Player (Audio)
• Flappy Bird (Physics + AABB + Math)
• Mini Games (States)
• Image Filters (Shaders)

📚📚📚

[0nkery]

- at the bottom. before continuing.
+ at the bottom, before continuing.

I'm not much into English grammar, but it feels like there's no need in comma at all.

[dannyfritz]

Probably doesn't need any punctuation at all there. 😄

[0nkery]

ggez provides EventHandler as a loop ...
or
EventHandler is the provided loop for us to use ... (but I'd prefer former).

[0nkery]

Good start! I believe you'll make an awesome thing.

[icefoxen]

I like your roadmap. Things we need to think about from a project perspective (mostly just recording what we talked about on IRC):

• We need to ensure the guide is maintained and updated as ggez continues evolving and new features get added
• It would be nice to be able to ensure all code in it is correct, via rust-skeptic or some other means
• It would be nice to be able to put the guide on the website, and have the website be the actual entry point to useful information rather than the github page
• We should at least think about the possibility of translations and structure it so they're easy to do if we ever get around to it.
• Do we want to make this the ggez guide, and commit to keeping it up to date, or settle for it having, I guess, "contrib" status where keeping it up to date isn't a show-stopper for making a release? I definitely want high-quality official docs, but also, getting everything shipshape for an official release is hard, and is only going to become more work as time goes on...

[termhn]

I think this is better put as, "EventHandler is a way for us to interface with--and implement our own logic on top of--ggez's internal game loop." or something similar.

[termhn]

Sweet! I like the direction this is going and am definitely interested in helping out as it progresses! :D

[itmuckel]

I like your style of writing (and I love emoticons).

The only thing I'm missing is integration with specs-rs, but as soon as I'm proficient enough in this I consider contributing a part. (I'm still developing a game that makes excessive use of specs-rs). Also this is not too important.

Regarding keeping it up to date: I think it's generally best-practice to have a PR contain changes to the docs as soon as it adds functionality or (more important) changes functionality. I think this is easier to follow, because changes to code and changes to docs are in the same commit/PR. 😄

[Ealhad]

In HelloGgez.md, we create the state s at line 116, but try to use state at line 176. Both should have the same name.

I think this is a nice guide! I especially like that you give some challenges/exercises at the end of each chapter.

[Ealhad]

In HelloGgez.md, we create the state s at line 116, but try to use state at line 176. Both should have the same name.

I think this is a nice guide! I especially like that you give some challenges/exercises at the end of each chapter.

[icefoxen]

@dannyfritz What's the status of this? Can we merge what's here so that other people can work on it?

[dannyfritz]

Yeah, you can merge this. I have a third one in the hopper I just need to format I can do another PR for later. Been going really slow as you can see. 😛

[icefoxen]

Awesome, thank you! No worries. Perhaps we can do one PR per chapter in the future, to keep things easier to put together piece by piece.

[ozkriff]

Hm, considering #311 do we really want to use glob imports in the guide?

[ozkriff]

https://docs.rs/ggez/0.4.0/ggez/event/trait.EventHandler.html

Maybe it's better to give links without patch version?
Like https://docs.rs/ggez/0.4/ggez/event/trait.EventHandler.html