[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
rpgoldman at sift.info
Fri Dec 11 19:36:26 UTC 2009
Philippe Sismondi wrote:
> As I read through this thread I have been asking myself what is most
> important to me as a recent student of Lisp and ccl. My desires as
> regards documentation are:
> It should (of course) be as complete and up to date as possible.
> Authoritative documentation should be in one place rather than
> multiple places. (That was the problem I raised in my post that led to
> this thread. I look in the manual but forget the wiki.)
> It should be available in some one-chunk offline format, html or pdf.
> Presently I most often rely on a simple text search of the ccl manual.
> I don't want to rely on a web search capability for searching manuals.
> (Maybe I'm a luddite in that regard.)
> I don't know whether community contributions would be good or not. I
> would be very displeased to discover that spurious or badly written
> stuff was creeping in. Technical documentation is not wikipedia; I
> rely on ccl docs to do actual work. I would find it sufficient to
> search mailing list archives for community input, I think.
This is why I suggested the annotation possibility. There would be a
low bar to put marginalia in the manual, but it would still add value.
By analogy, I wanted to keep the CLIM spec visible, but I liked having
marginal notes in cases of ambiguity, etc.
> So, my guess is that fancy semantic markup like docbook or restrictive
> wiki rules are probably more of a hinderance than a help here.
> Reasonable structural and stylistic rules enforced by convention
> rather than software are more likely to produce what I want to read
> and use.
The problem with that approach is "enforced by convention" really means
"enforced by copy editing," and copy editing hours are a scarce
resource. If you can delegate some of that to the tool, the tradeoff
may be worthwhile.
I understand, though, that any tool that enforces anything about the
format will of necessity be more difficult to use than one that doesn't.
I don't pretend to know how to make that tradeoff.
More information about the Openmcl-devel