Results 1 to 10 of 10

Thread: Move documentation to wiki?

  1. #1

    Default Move documentation to wiki?

    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).

  2. #2
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    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)

  3. #3

    Default

    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 :-)

  4. #4
    ClanLib Developer
    Join Date
    Sep 2006
    Location
    Bergen, Norway
    Posts
    588

    Default

    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.

  5. #5

    Default

    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.

  6. #6
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    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

  7. #7

    Default

    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.

  8. #8
    Serf Feral's Avatar
    Join Date
    Feb 2010
    Location
    Redding, CA, USA
    Posts
    3

    Default

    *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.

  9. #9
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    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.

  10. #10
    ClanLib Developer
    Join Date
    May 2007
    Posts
    1,824

    Default

    The wiki is now online

Similar Threads

  1. Novashell on the move...
    By Pleng in forum Novashell Game Creation System
    Replies: 7
    Last Post: 05-13-2008, 05:38 PM
  2. Docs... wiki page?
    By whisperstorm in forum Novashell Game Creation System
    Replies: 9
    Last Post: 06-07-2007, 12:24 PM
  3. Exception every time I try to move stuff
    By cpury in forum Novashell Game Creation System
    Replies: 9
    Last Post: 03-01-2007, 11:26 AM
  4. Can't move forward  :(
    By in forum Other RTsoft Games
    Replies: 3
    Last Post: 06-14-2003, 11:16 PM
  5. Can't move into town
    By in forum Funeral Quest
    Replies: 1
    Last Post: 09-08-2002, 03:18 AM

Bookmarks

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •