Hi, Just a few comments from a Chicken user.
I really like searchable, accessible and editable documents on the web. On the other hand, I have never used any docs shipped with eggs - it's simply to much hassle to browse the directories if I can type two words in Google. Wiki docs (and eggs concept) were the two main features that attracted me to Chicken, BTW. I don't want any API docs automatically generated from source code comments - when separated from the code these comments are just a pile of useless random notes. Documentation _must_ be written in separation from the code. Yes, it is an additional effort, bu if you can't afford it simply don't bother writing any documentation. -r. On Thu, Feb 14, 2008 at 7:54 PM, Elf <[EMAIL PROTECTED]> wrote: > > 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 > Chicken-users@nongnu.org > http://lists.nongnu.org/mailman/listinfo/chicken-users > _______________________________________________ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users