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@seul.org
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 <[EMAIL PROTECTED]> 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 Java Script
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
