Move documentation to wiki?

[genail]

Hey!

It's not the first time that when looking after overview about one functionality or another I found a little bug in documentation or outdated example like here:

http://clanlib.org/docs/clanlib-2.1/...detection.html

The last example reads:

<< "(" << cc.contour1->points[colp.contour1_line_start].x

But CL_Contour in 2.1.1 has got no points field but get_points() method instead.

This is to much effort to collect all those small mistakes and send the email or write a forum thread for such small changes. I think that the best solution is to move this documentation (or maybe whole clanlib main page) to some kind of public wiki so anyone can keep these pages up to date. This would be also great opportunity to write more articles and tutorials by anyone who wants to.


What do you think? I can lend a hand with this task. This may be also chance to setup a bugtrack (like trac).

[rombust]

Personally, I'm not sure it's worth the effort.

Very few people (alomost zero) send documentation patches at the moment.

I think this is because documentation is soo boring to write!

If the documentation is moved to a public wiki, we loose control of it, and it is open to abuse (spam etc). Unless somebody checks it 24 hours a day.

(This is my own opinion, other developers may disagree)

[genail]

SPAM problem can be resolved by registering with captcha system. Abuse is a thing that cannot be preserved but it happens quite rarely. And if so it is often fixed by "bright-side" documentation readers.

About controlling the wiki, one person can receive daily wiki diff as a mail. What's more you can install hook that will send a warning email when just commited change containing sensitive keywords (or many words that was not found in english dictionary, external links, etc.)

I also disagree that writing documentation must be boring. Some people are enjoyed of sharing their experience and wisdom if only they feel like a part of community. One writes when someone other will appreciate his work. It's true that most of documentation is written by developers theirself but still...


As great piece of wiki (and example) I'll give Orge3D wiki: http://www.ogre3d.org/wiki/index.php/Main_Page . Of course their community cannot be compared to ClanLib's.

I think it's really worth trying. As I said before I can lend a hand to set up things, move docs and maintain :-)

[sphair]

As usual the problem is with who does the maintainance. Very often someone wants to do some initial work, and then after a little while it ends up with the core developers once the initial responsible gets tired of it. What we need is a long term commitment to maintain it over time. If you want to try it out, and maintain the wiki, I'd welcome it.

[genail]

It will be a pleasure :-)

I only need to know what are capabilities of ClanLib homepage hosting server and discuss some other things too. I'll try to contact you through IRC channel.

[rombust]

The documentation is a part of the ClanLib SVN.

At certain intervals, admin developers (not myself) on the clanlib server press a magic button that performs a "svn update" to copy the pages and run the API documentation scripts.

The main pages (home page etc), only the admin developers have access to (which, imho is correct).

It would be amazing if ClanLib docs are updated Many thanks for the interest

[genail]

Nothing is impossible but I would leave doxygen and "old" API documentation as is and move overview documentation from svn directly to wiki (by removing html files from svn).

It's because edited wiki page could be overwritten and that's not what we want.

Over night I came to one more idea. It would be nice is code examples on wiki will do self-test to check if are still valid. I think it can be easily done.

[Feral]

*ponders* Going from a blank slate what might be the "ultimate" solution would be to mesh a wiki with doxygen output. Rather like a wiki "talk page" while maintaining the existing doxygen API documentation.

Perhaps just adding an automated link to each related wiki page from the doxygen output (can that be done?) would work and, in theory, keep the benefits of both.

Just sand in the wind though...

Oh, and PmWiki is pretty nice too, no database needed php based.

[rombust]

I feel the only way that users will provide documentation is to make the process as simple and quick as possible.

The new clanlib wiki should be online very soon. It uses MediaWiki.

Many many thanks to Genail for his help.

In theory, the wiki could go online now, but unfortunately gmail is currently blocking clanlib's email. Hopefully that problem will be rectified soon.

[rombust]

The wiki is now online