This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Names in libguile
Mikael Djurfeldt <mdj@mdj.nada.kth.se> writes:
> Yeah, but I'd like to fill this directory with lots of files
> associated with Guile. This is a need primarily for Guile
> development. It shouldn't be hampered by us hesitating whether
> something is good enough to put there. We also shouldn't hesitate
> to use it as a repository for documents about Guile.
I don't understand why you *wouldn't* want to include all the docs,
even the half-baked ones, in the source tree (whether you get that
tree via CVS or via tarfile).
What's the point in sorta-hiding them? If you're really that worried
that someone will misinterpret things in there, just put in in a
subdirectory entitled ./caveat-emptor-docs, put a README.FIRST in
there that says "don't believe anything in here", and put a line at
the top of each file that says, "Any or all of the following may be
rubbish -- you have been warned."
I tend to think you're much better off in this case making as much
information available as possible, even as half-baked devel docs, and
I think that even slight barriers like this to potential developers
are often a bad idea -- second guessing your future help can be a
tricky business. Further, as a guile library user, I've had a number
of occasions where the info docs weren't complete enough, and I had to
refer to the source to try and figure out which functions I was
supposed to be using, etc.
In those cases, it would have been nice if even totally unfinished
info on some of these topics had been available in
/usr/doc/guile1.3/unfinished-doc/ or wherever, and had they been
there, I would have been likely to submit patches correcting things I
found unclear or wrong..., and what if some not-so-technical user came
along and grabbed those half-finished docs and felt like translating
them to french/spanish/whatever, or just spell checking them? If the
docs are really half-baked, then that might not be that useful, but if
they were nearing completion, it might be an unexpected boon.
FWIW.
--
Rob Browning <rlb@cs.utexas.edu> PGP=E80E0D04F521A094 532B97F5D64E3930