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
_______________________________________________
Chicken-users mailing list
address@hidden
http://lists.nongnu.org/mailman/listinfo/chicken-users