For several months I have been trying to learn OpenGL to go beyond displaying a single 3D object. I have watched a lot of videos, read books, and lots of online documentation. In my opinion, the documentation on OpenGL is so poor that the technology would be dead today if it weren't for OpenGL ES and mobile devices and to a much lesser degree the Mac. Even for these platforms the use of 3D really isn't all that great. The vast majority of graphics on these platforms remains 2D.

But that's enough of my complaining. Here are some suggestions for those who aspire to create tutorials and other documentation.

First, indicate which version of OpenGL your tutorial refers to. Nothing has been more frustrating that reading through a tutorial only to discover it provides details about a version other than the one I have been trying to learn. In my case I have bee trying to learn 3.2core because that is what is available on my mac.

Second, define terms. I have read the specs for several versions of OpengGL. They are riddled with undefined terms. Many of these terms have only a passing similarity to other terms in computer science. A good example is "binding point." It seems like this should be a pointer of some sort. However, I have not found a single clear definition of the term. I can only infer what it means by the various vague descriptions that use the term. There are many other such terms.

Third, use figures to depict a process. Words don't always convey how a process works unless they are really well written. A figure, on the other hand, can go a long ways to clarify the meaning of text. I have found no figures illustrating the use of state variables, for example, and how they change as functions are called. But figures need not be limited to state variables. Using them, in my opinion, is a must.

Lastly, someone needs to write a really good explanation about vertex arrays, buffer objects, and vertex array objects and how to use these things to create entire scenes of objects. I am inventing my own techniques because, frankly, there is no good documentation.