[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
mdc at clozure.com
Fri Dec 11 17:56:44 UTC 2009
Tim Bradshaw wrote on 12/11/09 12:27 PM:
> On 11 Dec 2009, at 16:15, Robert Goldman wrote:
>> greed. The wikis don't "know" when they are talking about, e.g., a
>> function, although docbook and texinfo do. You can't have very simple
>> wiki format and have semantic markup (and good indexing) at the same
> I've only used a single, rather oddball, wiki system in the last
> couple of years, but I'd get around that by extending the syntax in
> the wiki to support the kind of semantic constructs you want.
I have found DokuWiki  to be useful for storing documentation. It
can be extended with "syntax plugins" to augment its syntax .
Because dokuwiki files are stored as plain text, it is possible for
other programs to operate on them fairly easily. (I can imagine a cron
job that generates documents from wiki content).
On the subject of motivation, wikis make it easy for people to
contribute and edit content, so they are more likely to. Finding a way
to control the quality of the contributions can be somewhat of a
challenge, but usually there are people who like tending the wiki.
If those that don't like to do such tending tasks can be somewhat
supportive (or at least not too hostile) to those that do, there is the
potential to get the benefits of useful documentation for, uh, "those
unfortunate people who can't just read the source code and figure it out
I have found wikis to work well for storing information, and though I
haven't tried generated more structured documentation from one, I can
imagine it could work reasonably well.
For the wiki to remain attractive to potential contributors, I think it
would be wise to guard against creating so many rigid syntax rules that
it becomes too hard to enter information. Then you just end up with
DocBook or Latex.
Finding the right balance of syntax complexity vs. expressiveness is
part of the subtle art of it.
Remember also that wikis can be searched, and in the restricted domain
of the wiki, search is often quite effective.
More information about the Openmcl-devel