the Fiddler.'s picture

Progress: Function Reference

A preview is available online at Documentation->Reference. Not 100% ready yet (contains private members, misses a stylesheet), expect regular updates.

Edit: stylesheet updated.


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
Inertia's picture

Good to see that OpenTK takes documentation more seriously than other unnamed "the source code is the manual" open-source projects :)

I'm curious though, is there any reason why a Wiki is avoided? Waiting for GL 3? It was mentioned in previous news that the Tutorials are html pages, so a Wiki might a good focal point for all Documentation.

the Fiddler.'s picture

I've given this some thought, but I feel that adding a separate wiki would have too high a maintenance cost without any real advantage over the current CMS. I'm playing with Drupal's 'book' module right now, which looks like the perfect alternative: it can contain pure html pages or even php code (something used for the function reference for instance), it allows online collaboration not unlike a wiki's, and it stays integrated with the rest of the site - seems like the way to go.

I'll start uploading content soon and hopefully this will become a collaborative effort in the future.

Edit: I haven't really used wikis in the past, so I may be missing something obvious. Is there something in a wiki that would make it more suitable than, say, a generic CMS for documentation?

objarni's picture

Hint: check out wikipedia.org, the worlds largest encyclopedia.. Wikis are quite useful :)

I guess a CMS (content management system) is just the general term for things like wikis.. A wiki is a CMS or am I missing something?

the Fiddler.'s picture

No, a wiki is just one kind of CMS. Wikis are useful, no argument there! It's just that: a) I can't think what a wiki can offer that drupal can't (apart from better scalability) and b) a wiki without a large community will grow stale over time (and even sites like opengl.org and delta3d.org fail to maintain their wikis).

So, I guess the real question is: what functionality is this site missing that would be solved with a wiki?

Inertia's picture

The Wiki is not a demand - just wondering. What I had in mind was that many GL Commands are part of a sequence of commands that are used together, it would be great for the programmers reference to link directly into a small example usage in the wiki, which in turn links to all it's used commands in the reference. Intellisense does a good job for the parameters of the methods, but for example it cannot tell you that you have to gen and bind a texture before it makes sense to call teximage.
Besides that, the biggest benefit of a Wiki would be the user-contributions so you don't have to write all tutorials/articles on your own, but allow a very brief explaination what is supposed to be documented on this single wiki page and (maybe even someone else) expand the stub at some later point.

The problem of opengl.org's wiki is related to restricted access. I can imagine it also has something todo with upcoming GL3 and that many GL2 articles will become obsolete.

objarni's picture

No, a wiki is just one kind of CMS.

Well not to be picky, but I did not state that ;)

For a function reference, a wiki is not great -- better to generate that from the XML docs, for example.

A wiki is great for explaining things in a more user-friendly way, like a programmmers manual sort of. But I don't know exactly what the CMS system you are using is capable of, maybe this is available (linking between pages, online editing etc.)