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

[Elf]

On Thu, 14 Feb 2008, a r wrote:

> 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 like searchable webdocs for browsing.  i also like searchable docs in 
the interpreter.  and i like the ability to generate arbitrary formats 
(say, pdf of the whole manual).   if (use/require/require-extension/load/etc) 
loaded documentation into the interpreter automatically (or there was some
flag to determine if it should do it, or something along these lines), this
would be more useful imho in the general sense even than webdocs, provided
it was generically searchable and well indexed.  (the previous statement
should in no way be taken to mean that i think webdocs should be removed
or obsoleted, cause theyre obviously both popular and highly used.  i know
im on the site a dozen times a day most days.)

the problem with web-only docs is that retranslation generally is unpleasant,
and primitives to make documenting this sort of project easy are sorely 
lacking.


> 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.

im in total agreement with you on this one :)


-elf