[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
mdc at etherboot.org
Sat Dec 12 11:17:53 PST 2009
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
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
- 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
- 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
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.
More information about the Openmcl-devel