Documentation

[Jan_97]

So I've been coding everyday in march so far and have thus spent quite a few hours working on my latest game project in pygame. Therefore i have been going through documentation/tutorials to learn as much as I need to carry myself forward. In doing so I have noticed that documentation is not as easy to learn from as I used to think. My main issue seems to be that I can never quite find any concrete examples of things I want to use, or learn to create by myself. So what I've been doing is simply just picking up a few things here and there from different sources and puzzling together solutions that can work the way I want it to work.

This actually has worked out for me (so far) I have been able to create everything I want to create, but I'm wondering if maybe I am making things more difficult than they need to be. In short, my question is simple. Could I just simply be looking for proper documentation in the wrong places?

I use pygame.org & this site for pygame sources and stackoverflow/github for other examples. It's just that I never find any clean cut examples showing exactly how a certain feature is supposed to be used unless I ask/post about it.

Usually examples are either oversimplified or not used in the way I want to use them, therefore making me having to manually change them up and doublecheck across other sources that I inderstand how to alter and use these features.

I have heard of other (more advanced users) usually run into this type of problem too, when their work uses features that are too specific to have any useable documentation on the web.

What's your take on this? How can i escape this "example hell" Is the best solution just to look at what others do and keep making my own takes on these things until i get it right?

[Larz60+]

So what I've been doing is simply just picking up a few things here and there from different sources and puzzling together solutions that can work the way I want it to work.

Oftentimes this is the best way to learn, you don't forget so easily. The only 'escape' that I have found, is to find a good tutorial on the subject, whatever that might be, and run it to the end. You'll know if it's a good one after the first lesson. I'll also add that I read the documentation as well, usually after the tutorial where it makes more sense.

But I still use the first method the most, have done for many decades.

[Jeff900]

I think the major downside of all the sources to find information is the fact that they usally use examples, which are not necessarely explain what you want to do. But that is not really the goal of that type of documentation I guess. But on the other hand, what's wrong with getting an idea of something and then explore further? When you think of what your goal is with your code you can get inspired by these sources. And as soon as you have the idea that, for example a specific library, suits your situation you can try it yourself and read the official documentation.

I usally recommend to read that anyway, especially to get an idea of the different kind of functions it provides. I do this a lot when working on my linux machine. In that case I always use the 'man pages', get inspired and just try things out. After all, you will need to try whatever is possibly enriches your coding skills.

[metulburr]

What you are doing is what I did to learn pygame.

Usually examples are either oversimplified or not used in the way I want to use them, therefore making me having to manually change them up and doublecheck across other sources that I inderstand how to alter and use these features.

I have heard of other (more advanced users) usually run into this type of problem too, when their work uses features that are too specific to have any useable documentation on the web.

I have ran into both of these issues. The first issue is true. You basically just have to morph the example to do what you want. They dont really have a database of various examples to do numerous tasks in which you can pick and choose.

The second issue is also accurate. I have made specific programs that once you get too far into, no one but those that are programming on it can help. Often that is just yourself. To get these answers you have to break down the code to be simplified to even get some help. But sometimes that is a long drawn out process. And other times you are just crossing your fingers that someone devotes the time to understand your game structure, etc. to help. That is why i say in my tutorials that is very important for organization for yourself and others when making the game structure. It is almost pointless to help those that dont bother organizing because those with knowledge have to understand their entire code instead of a single function that does one thing, for example. And other times people have to unwrap that example with their own code to even get help. Sometimes by doing this you figure out where you went wrong.

Eventually you will create your own database of features and it will just become your boilerplate code for any game you start. New people just starting out cant really use others boilerplate code for starting a game because they dont understand why some of it is there to begin with.

A lot of times creating a new question post for a specific problem to get help on that is the only way to go. You just have to go one step at a time.

[Jeff900]

metulburr, you are making a good point here. It made me thinking about what is really the point when programming software. It is not just about the actual code, functions etc. You can learn those from, well basically everywhere on the internet. But it's the way you use functions, the way they are providing a (part of) solution for problem you are trying to solve. This means you need to be creative, think out the structure, be able to explain what it is doing (or is supposed to do).