A tangential question is, will the samples be precompiled, or distributed in source form? If the dependencies are kept to a minimum and the build system is simple enough, the latter may actually be easier to support.
But that’s actual a little less important than deciding to what is going to be in the samples; how it will be presented (NeHe style? shudder); by whom it will be written. (First decide the scope of the material and then how to implement it).
My opinion is that each sample should present a concept in written form, accompanied by a short program that contains the minimal amount of code that implements the concept. A “sample explorer” would list all available samples, possibly with links to further information, articles etc.
It would also be great to have the online function reference available offline. I don’t know if there are legal issues with this, but seeing that PyOpenGL (and other bindings) already provide their own versions of the online docs, it should be possible.
One more thing: should the sdk provide its own utility functions, or should it link/use existing libraries? For practicality’s shake, I think the latter approach might be better: collect the “best of breed” libraries for each category (e.g. math, windowing, texture loaders, GUI, fonts, etc. taking maturity, usability, community and license into account).
Edit:
This is what I meant; C++ style comments have been standard since C99 as opposed to C89. C99 is not, however, necessarily that widely adopted. GCC lacks some of its features.
The only C compiler I’ve used that didn’t support C++ style comments was written in '88 for DOS. GCC 2.95 supports these and VC6 does too - there’s absolutely no reason to worry about this.
Using other C99 features however is probably a no-go.
Edit 2:
the main focus was the math library and we decided to stick with plain C.
What about existing math libraries? Intel/AMD both provide such libraries and there are many more to be found in the web. Is there really a need to write a new one from scratch? Yeah, I’ve been guilty of that thrice, in C, C++ and C# - but I think we should avoid unnecessary complexity wherever possible :).
Another thing to note is that we could modify/wrap existing APIs to make them fit together in a nicer way.