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.