Re: [Chicken-users] documentation issues...

[Alejandro Forero Cuervo]

> id like to entitle this next rant 'why wikis are highly suboptimal
> for documentation', if i may.

Well, I mostly agree with the points you are raising, which I would
summarize as 'having to edit text for hours using a web interface
sucks' (even if you use plugins or special browsers so that you are
actually using a real editor for textareas).

On the other hand, I think wikis have the draw of lowering the barrier
to making changes to the point where people reading documents begin
contributing.  The extent to which this happens varies greatly from
one website to the next (and even for specific pages in a website),
but there are several examples of why this can work greatly.

I started Svnwiki back in 2004 because I wanted a wiki system but I
was not willing to go through what you just did: editing something for
hours on an extremely limited text-editor risking just losing
everything because the connection went away.  On the other hand, I
wanted to lower the barrier to collaboration.  I've been using Svnwiki
for lots of websites since then and I'm mostly happy with the overall
experience.  I migrated my weblog http://azul.freaks-unidos.net/ to it
so I can write my posts through Vim (my favorite editor), commit and
call it a day.  I even support weblogs of other people
(http://wiki.freaks-unidos.net/weblogs) and installations such as
http://fsfla.org/svnwiki or, obviously, Chicken's.  Of course, there
have been some problems in the past when I have added lots of features
in small intervals of time and I have introduced some unstability.
Furthermore, installing Svnwiki has a reputation of being hard, as you
have to (1) set up an Svn repository and (2) set lots of properties on
it.  Thirdly, getting all the dependencies installed, while not rocket
science, had some complexity that should be eliminated (some day I'll
get of my lazy butt and turn the Svnwiki extensions into eggs of their
own so that they can be installed with chicken-setup, finally solving
this problem).  Fourthly, there seem to be some infrequent errors with
the use of sqlite involving concurrent accesses to the database, which
I haven't really got to debug or try to solve.  With all that said, 4
years later I'm mostly happy with the results. :-)

That said, you seem to also mention another point which is that, to
you, the wiki syntax we use seems to be limiting:

> what remains relevant is that its bloody hard to document anything
> even slightly nontrivial in it.

While this is not my perception, I've heard this claim in the past.  I
would like to see if Svnwiki can be improved in this area to make it
easier for you and others like you to use it.  Care to give me a few
examples of concrete syntax forms that you think we should support and
what they should parse to?

Thanks and happy editing! :-)

Alejo.
http://azul.freaks-unidos.net/