[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Public WebGL] WebGL Reference Pages






It's been suggested WebGL should have a set of Reference Pages similar to the OpenGL ES reference pages

http://www.khronos.org/opengles/sdk/docs/man/

What do you think? Important? Not important?

If you think we should have them how do you think they should be implemented? There's been 2 suggestions so far

1) Check them into the repo.

pros:
  Easier to automate some things
  Changes can be approved

cons:
   Much more work to make simple changes or contributions

2) Put them on the Wiki

pros:
   Much easier to contribute and edit

cons:
   ??

Someone pointed out that Mozilla's experience is that Wiki > Repo when it comes to docs. They switched from docs in a repo to their wiki system at MDN and saw a big increase in contributions, especially from a people that hadn't previously contributed to code.
Hey, that someone was probably me, and it is also true that all of Mozilla's docs are wikis, but just for the record, I didn't mention (or know about) an actual switch from repo to wiki --- I was just talking out of my humble common sense ;-)

I stand by my claim that a wiki will greatly increase peoples' willingness to contribute. Note that in some case, that can be a downside as some areas can benefit more from elitism / high barriers to entry. But in the case of WebGL docs, I believe that a wiki will be beneficial overall.

Benoit

WebGL, being a WEB spec, I'd like to suggest that where it makes sense, live examples are part of the docs. We can check samples into the webgl repo and use iframes to stick them in the reference pages.

Thoughts?