oyvindra's picture

Communication and Documentation

Hi, OpenTK i great, but I think it could be even greater if it got more users, and the only thing I've seen people complain about is the lack of documentation.

What do people think about a simple wiki system for easy editing of information?

And also, are any OpenTK users on IRC? I have looked at the quakenet channel, but never seen anyone there... How bout a small one on freenode.net?


Comments

Comment viewing options

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

hello oyvindra,

the current documentation is almost a wiki-system. Everybody can edit pages ... but of course it would be nice to coordinate the updates with the page author.

I think the documentation is pretty good ... OpenTK is mainly a wrapper, thus the wrapped parts don't need to be documented ... except for methods that don't follow the traditional opengl api.

greetings

georg

objarni's picture

The parts that needs documentation, is the non-wrapper parts. OpenTK is more than a wrapper!

- GLControl needs documentation
- So does GameWindow
- All utilities-related functionality needs documentation (fonts being the prime example)
- Generally, all such documentation should be "tutorial/example"-oriented, ie. be targeted towards users of OpenTK, not developers of OpenTK.

Short comments about the current system, which I call the "book system":

- If I change a simple typo in the book system, I suddenly become the author of that page, something I did not intend.
- Messages posted below pages of the book, stay there for long time periods. A problem seems to be that only administrators of the site may delete such messages. A better system IMHO would be if not only administrators, but also page-owners could delete such messages, or that such page-discussions are put not below the page but on a separate link, like the Discussion-link seen on wikipedia for example.
- Collaboratively editing the main OpenTK site might seem a little intimidating for the casual OpenTK user ("What? Should I really edit the official OpenTK documentation?"). One idea is to have a separate, off-site cook-book wiki for OpenTK users. I think there are a few alternatives out there on the net. Allegro has that (allegro.cc is a user-driven site separated from the main allegro development site)

the Fiddler's picture

Agreed, the book system is not ideal, but it's better than nothing. It's like a wiki, only without the advanced functionality (and the spam).

Personally, I believe docs should have two parts: function reference and user manual. These should be available both online (on this site) and offline (distributed with OpenTK).

A wiki doesn't really help with this, unless you have *a lot* of active users. What *does* help is a simple API , where you don't need to read the manual before using it (no, fonts are not an example of this - not yet ;)). Extensive explanations, caveats etc could be an indication that the API should be refactored. That's my experience, at least.

Right now, about 90% of the public API of OpenTK should be more or less documented with simple inline docs (excluding OpenGL and OpenAL functions, where this is not feasible). "Stable" parts generally carry more comments than "unstable" ones. There also is at least one boring example for each major part of OpenTK (GameWindow, GLControl, Graphics, Audio, Input, Fonts).

Once more parts are stabilized, more extensive docs will appear - but it's not really feasible to write extensive docs when the implementation/API might change.

Examples are especially welcome, as are comments on the API (e.g. "fonts are convoluted", or "I couldn't find how to make a GraphicsContext not current, is this possible?"). It is difficult to improve the API without such feedback.

@objarni: By the way, what's wrong with GLControl? I always thought this was one of the simplest parts of OpenTK: just drag & drop it on a Form and hook the paint event - just like any other Windows.Forms control.

objarni's picture

@objarni: By the way, what's wrong with GLControl? I always thought this was one of the simplest parts of OpenTK: just drag & drop it on a Form and hook the paint event - just like any other Windows.Forms control.

I think it is really good!

But it lacks thorough documentation:

1. How do I choose what h/w buffers to use? Stencil-color-depth and so on.
2. How do I use multible GLControls correctly?
3. How do I use the fullscreen trick?
4. Maybe more stuff can't remember right now

These topics have been up in the forums every once in a while, but they stay there and never show up in the book.

There also is at least one boring example for each major part of OpenTK (GameWindow, GLControl, Graphics, Audio, Input, Fonts).

I guess you mean the builtin-examples, precompiled in the OpenTK package. I view them more as "stability tests" to verify features on different platforms. They have a documentation-like purpose too, but that is secondary, IMHO.

Once more parts are stabilized, more extensive docs will appear - but it's not really feasible to write extensive docs when the implementation/API might change.

Well, yes some documentation may have to be rewritten. Is that such a big problem..? I think a somewhat misleading, but 90% correct tutorial is better than none. Eg. when I read a tutorial on how to use Inkscape the other day, drawing flags and stuff, the tutorial was somewhat dated (wrong GUI dialog pictures eg.). Did that stop me? Not really. I was well off anyway -- the details I can find out anyway. It is the flow/thoughts/model that is important to grasp. The same goes for OpenTK fonts, GameWindow or GLControl. [The OpenGL "way of thinking" is something one should grok somewhere else.]

I am trying to improve OpenTK from a users viewpoint. When I look for programming libraries, one of the first things I try to find out is "How well documented is it?". I think it is fair to say 50% of the value of a library is it's documentation. Would you use OpenGL if it was IntelliSense only?

flopoloco's picture

When I started using OpenTK about 4-6 months ago, (as a newbie) I found myself porting lots of existing C++ and fundamental OpenGL concepts, I hope that there's a way to help new users avoid this... My opinion is that a Wiki is essential but only aiding the OpenTK experience (plus enhancing the learning curve), documentation I imagine should be strictly limited to technical stuff. ;-)

Is it a good idea?

objarni's picture

"Documentation" is a little vague, agreed. Maybe being more explicit on what kind of documentation we are talking about would clarify things.

Kinds of documentation

  • System documentation: describes the design and architecture of OpenTK. Primary audience: OpenTK developers.
  • Programmers guide: tutorial-like explanation of using OpenTK. Abstraction essential! Primary audience: OpenTK users.
  • IntelliSense: what you see popup in the IDE while developing. Details essential! (but not as detailed as the reference) Primary audience: OpenTK users.
  • Builtin example: a short snippet of code excersizing a certain aspect of OpenTK. Primary audience: OpenTK users.
  • Technical reference: detailed explanation of each method, class, argument. Details essential! Primary audience: OpenTK users and developers.

I think there has been a focus so far on Builtin examples and IntelliSense. I don't know how much effort has been put into System documentation or Technical reference.

Among all of them, I value Programmers guide the most, since that is the most productive kind of documentation for the OpenTK user (that includes me and most of the guys on this site, I would guess).