This isn’t really dealing with the OpenGL API, but how the spec is written. In the ARB_Vertex_Buffer_Object extension it was real nice of the spec writer to include a little section that contained examples on how to use the extension. I know an spec is not suppose to be a tutorial or anything, but a short example would be really helpful for programmers that wont fully understand an extension just by reading the spec. It would be nice if future extensions included code snippets on how to use an extension.

I’m always up for more/better documentation.