[Chicken-users] documentation issues...

[Elf]

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

approximately 9 hours ago, i noticed that the documentation that i had
changed in the http wikidoc wasnt generating correctly.  (for those 
wondering for future endeavours, its not possible at the moment to 
do nested tables directly.  or tables with any wiki-markup at all.  or
any other markup.  or ... you get the idea.)

running through all those hoops only took about 2 hours before i realised
that no markup would work inside existing markup.  luckily, theres the
scheme tag, to allow embedded evaluation of expressions.  (and again, for
those wondering, yes, the entire thing is generated via about 90 calls
to (display) with static strings.)

so we're about 4 hours in now, and things work about 95% of the way.  its not
handling margins properly and its not aligning text as specified.  no biggie,
right?

this took the following 5 hours.  and theres absolutely no reason why it 
should have taken more than 30 mins from the beginning, but im more than 
willing to allow for strange edge cases taking a bit longer.

so why did it take so long? 
a) im stuck in a tiny window in a tiny screen with no real text manipulation
   abilities. 
b) theres no search and replace.  theres no way of even killing lines off. 
c) cut and paste is fickle about where the mosue is, not where the cursor
   is.
d) theres no undo.  theres no redo.  theres no means of even taking it offline
   effectively.
e) and the real dealbreaker.... once i was 99.99% done .... and loading the
   preview... it froze in the middle of displaying.  claimed it was done (ie,
   not a network error or something.)  theres no buttons at the top to force
   a save or anything.  meaning at 8.5 hours in, i had to start over almost
   from the beginning.

now, if we're going to be doing a hackathon with a focus (so far) on
documentation and participation, how long do you think it will be before 
people get sufficiently frustrated that they throw up their hands and leave?

wikis are not a viable solution for documentation that rarely requires 
editing and even more rarely needs editing by the world at large.

they are an excellent means of handling bugtracking, issue requests, 
public discussion, docs that DO get edited frequently or randomly, etc.

they are not an excellent means of documenting a project.


i am not in any way trying to criticise the excellent work done by 
alejandro in creating the wiki, nor mario in his tireless maintenance of
the wiki site, nor am i in any way advocating for the removal of web docs,
nor saying that the wiki sucks, nor am i criticisng those who think 
that everything should be through the wiki.

i am recounting the reality of the last half day of my life.  i am trying 
to raise what i consider to be a legitimate question on the wisdom 
and prudence of continuing to force a system to operate far beyond its 
original intent in design, and whether massively expanding its role is
really such a good idea.

-elf