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

[a r]

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