This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]