[gambit-list] Adding docs to wiki?

Christian Jaeger christian at pflanze.mine.nu
Sat Nov 29 09:04:13 EST 2008


Ali wrote:
> Hi there, I'm new to Gambit and it looks like an excellent bit of software.
>
> I was wondering whether or not it would be a good idea to copy the docs onto
> the wiki system.
> I'd be more than happy to copy the text across and wiki format it if
> desired.
>
> As I see it this would have the usual benefits of a wiki,
> but the disadvantage of having 2 copies of the docs which need to be
> synchronised.
>   

What will be different from the current possibility to change the 
documentation, namely using a Gambit Git checkout and a text editor to 
edit doc/gambit-c.txi in texinfo markup?

* it may be newbie friendlier (web browsers and wiki markup being the 
tools first used by new computer users nowadays);  it may be 
questionable how much of an advantage inviting newbies is actually, though

* it allows to split the docs into smaller units; but I think the 
existing texinfo converters can already do that, too

* wikis may have a nicer default layout than the currently offered html 
output of the texinfo converter: but I suppose that could easily changed 
too, if it matters at all

* it offers a more informal way of passing over thoughts, i.e. less for 
changing the actual documentation but for adding comments; I think this 
would probably be a good thing, but I wonder whether it wouldn't be a 
better solution to just have an annotation functionality for that; 
examples for such user annotated documentations:  
    http://www.php.net/manual/en/tutorial.firstpage.php
    http://dev.mysql.com/doc/refman/5.1/en/apache.html

* the versioning functionality in current wiki systems is much worse 
than something like Git; not only don't they offer distributed 
versioning, but also almost no tool access to work with; so merging back 
changes which happened on the wiki to the Gambit sources will be a 
manual process just as it will be a manual process to update the wiki 
documentation with changes happening in the Gambit sources; you should 
probably be willing to be the manual replacement for good tools for both 
of these directions.

I've been thinking for some time now that it's time for someone writing 
a wiki with a Git backend for storage; and optional forking for updates, 
so each user can work with his own branch [if he wants], [either online 
or offline], before merging back changes to the canonical location. And 
if that wiki would support texinfo as markup [or something that offers 
lossless conversion from/to texinfo, or Gambit moving to a different 
markup] then it would all become much more workable. Since there are 
some web frameworks for Gambit out there already, why not start such a 
wiki implementation? That would really be wonderful, even just for 
working with "normal" wiki content, not especially documentation. I'd 
help with the Git interfacing.

Christian.




More information about the Gambit-list mailing list