[Openmcl-devel] ccl manual (was Re: trace on recursive functions)

[Robert Goldman]

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.

best,
r