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

Re: [Public WebGL] WebGL Reference Pages

On 12/08/14 11:56, Gregg Tavares (社用) wrote:

On Tue, Aug 14, 2012 at 11:10 AM, Mark Callow <callow_mark@hicorp.co.jp> wrote:
On 12/08/13 19:15, Benoit Jacob wrote:
On the one hand, we have markup language that make it easy to write documents. On the other hand we have XML which gives automation but is a pain to write by hand. The only document writing system that combines convenient markup with good large-document-structuration-and-automation features, that I know of, is LaTeX. From the looks of the OpenGL [ES] PDF spec, it seems that it's made in LaTeX, for example (maybe someone can confirm). But compared to a wiki, this will increase the barrier to entry quite a bit.
I don't think enabling trivial modifications at the expense of creating an immense amount of manual labor is the right trade-off.

The point of the pages is as information, not automation. Sure automation might save some work but as has been demonstrated with not only the OpenGL and OpenGL ES man pages but also with just about every other project that has docs in a repo vs a wiki, making it easier to edit leads to more and better info.
Automation != docs in a repo. What it means is using a format that carries semantic information about the content. Such a format could easily be on a server that allows editing of the pages. Wiki's are just one type of web page that can be edited.

Incidentally it is not hard to find examples of wiki-based crowd-sourced documentation with a lot of out-dated information.