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

[Marty Connor]

Let's look at this problem from a few different perspectives in order to 
examine it a bit more generally.

First, a general observation:

   Documentation serves a number of purposes and serves
   a number of audiences with differing learning styles.

CCL is an Open Source (GNU LGPL v2.1) implementation of Common Lisp. 
This carries with it (for better or worse) the implication that useful 
contributions of code, testing, and documentation from those who use and 
support the software are encouraged (or at least not too strongly 
discouraged).

The principal developers of CCL is Clozure Associates, which is a 
company which provides world-class software and services.

The reason this is important to note is because it supports the 
observation that Clozure is serving a wide variety of users and clients, 
with differing needs, wants, and expectations.

For example, the needs of a company with a mission-critical applications 
may be markedly different from the needs of a solitary hobbyist doing 
research into a new way to process semantic information.

With these ideas in mind, I make the following observations and suggestions:

  - A single type of documentation will not serve all users.

  - There is room for multiple kinds of useful documentations

    Examples:

    - CCL Reference Manual (exists) http://ccl.clozure.com/manual/
    - User Guide (manual above seems to include this)
    - Getting Started Guide (manual above seems to include this)
    - Application notes
    - Case studies
    - White papers
    - Mailing list archives (searcheable)
    - Video tutorials, case studies, examples
    - Presentation slides

  - Somebody needs to coordinate and care for documentation in order
    to maintain quality, coherence, and usefulness

  - The cost/benefits proposition for such a task may mean that it is
    low in priority for Clozure, since customers generally won't pay
    directly for general documentation.

  - Given the opportunity, community members are often very willing to
    contribute documentation.

  - A wiki can be a very good way to encourage community members to
    participate in providing documentation.

I think the current discussion has gotten a bit stuck because discussion 
has focused on a classical monolithic approach to documentation, and 
tools to facilitate that approach.

The monolithic manual does work well for some people, particularly those 
with strong academic backgrounds.  In the LISP community this kind of 
background is fairly common.

I would suggest that the tension and desire to evolve our means and 
methods of documentation is driven in no small part by the fact that it 
is possible to use search engines and widely distributed knowledge to 
accomplish what once was impossible -- to do useful work without reading 
a reference manual for the software product involved.

Even at my age (52) I have mostly transitioned to online sources for 
primary documentation, and I find that search engines work extremely 
well for many cases.

There was a time when I preferred to read/skim a manual cover to cover 
when approaching a new software product.  Not so much anymore.  When 
learning to use Latex, I found most useful information on the web, and 
bought a few books from Amazon for reference.  I have not needed them 
very much.

Since CCL is a standards-compliant Common Lisp, this makes a lot of 
sense -- the things one wants to know that are special about CCL are 
often interpretations of the standard, or extensions to it.

These might be better served as application notes or as topics of 
discussion on a mailing list.

This leads me to the notion that there is already a lot of very useful 
(and findable) documentation for CCL.  What is lacking is coordination 
of the documentation efforts.

Since the most highly technical documentation is done by the core 
implementers of CCL, the toolset for that documentation must be 
something they are comfortable using.

Traditionally this mailing list has functioned as an important source of 
up-to-date documentation, and I am sure it could be mined as the source 
for dozens of application notes and documentation updates.

So for me it comes down to some basic qeustions:

   - What kinds of documentation is needed?

   - Who will be responsible for creating it?

   - What tools are appropriate for each kind of documentation

   - Who will be responsible for editing, organizing, and maintaining it?

I offer these thoughts in the hope that they will move this discussion 
along, and perhaps generate additional useful ideas.

Marty