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

[Marty Connor]

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
>> time.
>
> 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 [0] to be useful for storing documentation.  It 
can be extended with "syntax plugins" to augment its syntax [1].

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 
themselves" ;-)

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.

Marty

[0] http://www.dokuwiki.org/dokuwiki
[1] http://www.dokuwiki.org/syntax#syntax_plugins