OpenGL shortcomings?

[ul][]The documentation (or specification) of OpenGL is not very helpful. Sometimes, the same functions are used, but with a new meaning, compared to deprecated versions of OpenGL. This adds to the confusion.[]OpenGL is hard to debug. It is back to the dark ages of programming where you had to follow the adage never change more than one thing at a time. If something goes wrong, the usual result is the black screen of death.[]OpenGL follows, to a large extent, the programming concept of global variables. A failure to glEnable() something, somewhere, can have global effects elsewhere.[]There is an abundance of helpful tutorials on the Internet. A majority of these are for deprecated technology, and gets beginners started on the wrong track. Especially as they look very simple. For a start.[]I have had problems with the terminology. For example, the first time you see Associates a generic vertex attribute index with a named attribute variable you start to wonder if it is some foreign language. This could have been helped by a link to concept definitions.[/ul]There are some extenuating circumstances, of course:[ul][]The technology of modern 3D shader based programming is complex. This is not a fault of OpenGL, but it makes the learning curve steep.[]The specification is an implementation specification, not a user guide.[]I suppose the use of global states improves efficiency.[*]Getting started with the immediate mode is easier to understand for beginners.[/ul]

What is the purpose of this thread? I did not see a question.

-I would not use the specification to learn if I was a beginner. However, it tells you what the a parameters for a function are and also the error codes it would raise so I suppose in that respect, it can be used by a beginner.
-What do you propose for the black screen of death?
-The GPU is a state machine. You enable blending and disable blending. You enable the depth mask or you disable it. etc. All that stuff should be reported by your “engine” or your gDebugger so that you can see what the GL state is.
-The internet is the Wild Wild West. Viagra adds. Organ enhancement adds. Nudity. Old OpenGL tutorials.
-There is the Wiki : It can be edited by you and other people of the community.

-Personally, I think immediate mode is a waste of time. You can learn it on your first week and move on to IBO/VBO (GL 1.5) as quickly as possible.

Khronos mention a restructuring of the OpenGL spec that they were starting to work on after last years SIGGRAPH event:…L-Ecosystem.pdf which should help.
Also reducing the number of undefined + implementation defined areas as also mentioned in that document should help a bit too.