Documentation lacking

[thi <ttn at mingle dot glug dot org>]

Derry Bryson writes:

 > I really don't want to create any enemies here, but I think it
 > might be useful if I express my opinion.
 > 
 > [gist: documentation lacking + anecdote]
 > 
 > Perhaps I am simply stupid (or am not looking hard enough), and can't
 > understand the documentation provided.  Or, perhaps, the documentation
 > is not sufficient.  Come on, I understand programmers not wanting to
 > document code, but if you want a library to be useful to others you have
 > to at least document the basic ideas and functions provided in the
 > library; not to mention how the library should be used.

hey, stupidity is never simple.  take it from an expert... :->

it's well known that guile documentation is a weak spot.  so, what can
we do about it?  there are four approaches most commonly found in the
real world of limited contributor time and virtually unlimited project
requirements:

(1) degenerate case: do nothing, abandon guile due to insufficient docs
(2) point out hole, hoping for those who can fill it to fill it
(3) point out hole, and fill it oneself as best as possible => contribute
(4) research the source for personal projects (as a user), and keep
    that info to self

IMHO, (3) is most preferred, but historically guile development
(including docs) has not held open arms to random passers-by.  i think
this stance is ok for code, but for docs, it's extremely inhibiting, and
leads to a lot of (4) happening.  that is, because guile is compelling
enough (for some), people do take the trouble to dig through the source,
but their hard-won insight is not captured due to high entry barrier to
contribution.

having said that, w/in the last month or so, Greg Badros (a guile
maintainer) has announced he is focusing on documentation, initially of
the source-extraction kind, but also the rest of it (manual, internals
doc, etc).  my suggestion would be to scope out the area of most
frustration (perhaps everything, how about a "tips-and-tricks" doc?), do
the writeup and submit it.  i believe w/ greg's help there will be a
good chance it can find a place in the guile-doc tree.  in this way, you
exemplify (3).  on the maintainers' side, they would do well to adopt
some kind of fast-path for doc submission and adoption.

lastly, a large part of guile documentation lies in the mailing list
archives, where many many topcs (including documentation and the lack
thereof) have been discussed in great detail.  granted, this is a poor
substitute for well-indexed documentation; hopefully that will change
soon.  in the meantime, if you have questions, feel free to ask -- the
answers thus become part of the archive.  btw, if you're looking for a
project, i have this refbot idea that we can discuss off-list.

 > This is only common sense.

how dare you imply that this bunch subscribes to that concept! ;->

thi