12

I guess the question speaks for itself.

Examples: OpenGL introduction seems too lengthy and more of a tutorial (both Mac OSX and Windows versions), 3D Math starts with C++ templates and then delves in linear algebra and GLSL, this one even includes how to download and install a library.

Is Documentation a more user-friendly/up-to-date/concise (take your pick) version of manpage-esque reference documentation or is it supposed to be extensive tutorials?

8
  • 2
    IMO the OpenGL tutorial is not very useful. It's very specific (OpenGL 4.1, Cocoa, Objective-C, example code that can't easily be expanded.) And WGL and GDI are two very specific technologies that are unlikely to be useful in a general OpenGL context. Just looks like an overall bad tutorial to me. Jul 28, 2016 at 14:23
  • @uh I have added general-purpose expandable context creation code using SDL2 (pending review), but how is someone going to find it in this mess? C tag isn't too better either
    – strNOcat
    Jul 28, 2016 at 14:26
  • The amount of permutations is probably going to dilute the useful information. I think it's better to teach general principles like matrix transformations, resource pipelining, vertex buffers, etc. Things that are unlikely to be tied to specific platforms/technology. AKA I find the 3D math to be better. Jul 28, 2016 at 14:29
  • Since OpenGL doesn't provide any window creation API, there would have to be a bit of boilerplate to get off ground. That is understandable. Blog sized entries explaining WGL or Cocoa's internals are not, atleast to me
    – strNOcat
    Jul 28, 2016 at 14:31
  • I don't recall the source but I remember somebody writing about how OpenGL code examples are pointless because you cannot generalize. Even boilerplate examples are going to vary significantly. I think OpenGL is one of the examples where the copy/paste example format does not work for Documentation. Just teach the hard stuff (quaternions, etc.) and leave the boilerplate to google. Jul 28, 2016 at 14:34
  • 1
    @uhohsomebodyneedsapupper: But quaternions have nothing to do with OpenGL. There are no OpenGL APIs for manipulating quaternions, GLSL has no specific facilities for dealing with them, etc. Now obviously, OpenGL applications can use quaternions. But quaternions are just math, not something that is specific to OpenGL. So why would they be documented under the OpenGL tag? Jul 28, 2016 at 14:36
  • @uhohsomebodyneedsapupper That makes sense too. Infact, there doesn't seems to be any mechanism to document an API for a particular language, which means every entry will be riddled with implementations in multitudes of languages (and using multiple auxillary libraries). Language tags are indeed a bit cleaner (Lua seems relatively good)
    – strNOcat
    Jul 28, 2016 at 14:38
  • @NicolBolas It's a sliding scale of whether you want the topic to be an annotated guide to the API (of which plenty exist) or to cover general topics with OpenGL specific code. Jul 28, 2016 at 14:38

1 Answer 1

1

Looking through the content, there seems to be a lot out of place. In part, I expect this is a remnant of our QA culture that frowns upon multiple answers to the same question.

No, examples are not supposed to be tutorials in themselves. All of the content within the example should be relevant to the main title. Anything else needs to go somewhere else, maybe another example on another topic.

  • Setup on Windows has about one paragraph that is actually about setting things up. The rest is not about that.

  • The introduction to matrices is better, but I still see too much information that doesn't qualify as an "introduction to matrices". If I wanted to learn about translation or scaling, I would look for something titled "Translation" or "Scaling" respectively.

  • GLM does not belong here at all. Once qualifies for Docs (I suspect people misuse instead), the example/topic belongs there.


As for the other question (from the comments):

But quaternions have nothing to do with OpenGL. There are no OpenGL APIs for manipulating quaternions, GLSL has no specific facilities for dealing with them, etc. Now obviously, OpenGL applications can use quaternions. But quaternions are just math, not something that is specific to OpenGL. So why would they be documented under the OpenGL tag?

You would document quaternions in the OpenGL tag if there is something OpenGL-related to document. And you have provided some very important information for those learning the technology: OpenGL has nothing specifically created to deal with them. The question you would answer is then: what would one do instead if one needs a quaternion in OpenGL?

By providing useful examples, it not helps as something to copy-paste; it also reinforces the syntax and methodology of programming (and stuff).

0

Not the answer you're looking for? Browse other questions tagged .