Re: [pygame] pygame.org website update

Hi Phil,

I know you don't write the docs that is why I had asked to interface with the document writers. I have read the Pygame docs and have gone through them now one at a time and try to copy the examples if they exist and run and test them. Even adding stuff to see what the results are.

But in each case they either explain the method or instance with another one which uses the same words. Then you end up going round and round trying to figure out what is being said. Trying to figure out how and when I can ever use them.

In other words they write the documentation as if you already know the language, which is not a good way to do it, unless a reference only, a quick reference. But not for the tutorials and such.

I had used PHP as an example but that was a poor choice. The best one is the _javascript_ which is what I used to learn the language and write my first web based game from.

I was suggesting this format because it is the best one I have found out there. Having both the function, the parameters, an example, and even a format where it is run in so you not only can see the usage, but even test it out. But of course being a web based language then all they have to do is place it on a web page. Which does make it much easier to use. But Python and Pygame you have to have all that stuff up and running on your computer.

But doing the class examples I did learn a little but when doing something like self on self with little to no explanation to what is going on makes it so much harder to understand when you use the same words in the explanation that you are also defining.

So, I hope those who write to docs can understand what I am talking about. I do get stuck so I do have someone I can write to and get me an example to understand, but when some explanations mention variables, but give no list or explanation then your mind just blows and the hands go up in the air. What I am talking about is when I got to the examples of random and other stuff. There were variables given for examples but not a complete list or any place to find such a list. The reason why I mentioned the W3 school examples. For it seemed that there were many things that you could plug into random but no clue where to find them.

But I come from a unique perspective. I can not go out and purchase a book, which there are many explaining Python and Pygame, because I am totally blind and have to rely on text based web sites. I found that my best calculus teacher at college was the one who placed a picture on the black board, explained that picture in detail, to also explain the formulas that drew those pictures. For a picture, no matter the form, speaks a thousand words.

I was sighted when I first took calculus, but even when taken it again when blind, the same thing worked. When the teacher explained the formulas it all made sense when drawing graphs and pictures...and also describing them.

So, I agree with you, I do hope those who write the docs that read this list do understand what I am talking about. Then possibly re-write the docs with just one more addition. Simple examples that give the results of the usage. And the function also has all the variables that are a part of its make-up or event.

That would be the best and ultimate tutorial and docs on any programming language.

Thanks Phil.

Bruce

----- Original Message -----

From: Phil Hassey

To: pygame-users@xxxxxxxx

Sent: Sunday, October 21, 2007 2:46 PM

Subject: Re: [pygame] pygame.org website update

Hey,

I don't maintain the documentation or the contents of the wiki... but I bet those people read this list and can comment. Seems like the need here is a link to the python tutorial maybe. If that would be helpful, feel free to add that to the wiki where you think it would be most useful:

http://docs.python.org/tut/

Thanks!
Phil

RR4CLB <chester_lab@xxxxxxxxxxxx> wrote:

Phil,

    You should contact the people who do the tutorials or documentation and have them give better examples. A clearer way with more examples which explain all the variables inside all events and commands in Python and Pygame. I find the documents use the same 3 words all the time but are meaningless unless a detail of what is being said is shown; class, instance, method, class instantiation...Blah, Blah, Blah!! Eventually you do not know what there talking about because they keep on repeating the same words to explain themselves, thus all is lost in the reading.

    I am giving you an example of just one page of the W3 schools and how they do there page formats. The better one to get a hint on is the _javascript_ tutorial where they gave examples which are not only displayed but you can click on to edit, modify and even run so you can see what the function does and even change it to see what it does to the edited version. The perfect interactive tutorial which allows you on line to learn and even play with the examples to learn more by doing and experimenting.

    This would be the best way to have the web site displayed with both learning and learning tools.

    Below I first give you the link to all the tutorials and you can select from there. The PHP one I just picked the page for the math function and all its possibilities. All functions have a link to show examples. In _javascript_ there would also be an HTML page to test it out.

    To even try and find all the variables for the Pygame functions and what is used you have to search and search and see who may have done it or use the Dict function to expose it but even then there is no explanation on how to use that to expose functions and there content...

        Bruce