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

Re: [Public WebGL] WebGL Reference Pages



On Tue, Jul 31, 2012 at 11:23 AM, Gregg Tavares (社用) <gman@google.com> wrote:
What do you think? Important? Not important?
Would be useful.
 
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.

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?
A few comments on the form of the reference pages, they're not very friendly. The graphical representation is very oldschool and the way to navigate them is cumbersome at times. I'd volunteer to a draft of how this could be better.

I can see the advantages of repo integration, yet at the same time, community involvement with a wiki would certainly be better. Maybe this can be combined in some form where you can reference auto-generated parts from wiki pages.