documentation changes (was Re: [pygame] pygame.org website update )

["René Dudfield" <renesd@xxxxxxxxx>]

Hello,

can you please provide an example of what you mean?  For example the
Rect.inflate method.


We did plan to do an automated generation of a list of uses each of
the objects.  So it would grab text from the example, and provide a
link to it.  Much like how the pyopengl docs work.

Cheers!


On 10/22/07, RR4CLB <chester_lab@xxxxxxxxxxxx> wrote:
>
>
>
> 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 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