Subject: Re: mechanised documentation and my business model solution
From: Rich Morin <rdm@cfcl.com>
Date: Fri, 7 Apr 2006 00:15:36 -0800

At 8:56 PM -0800 4/6/06, Ben Tilly wrote:
> ... The ideal system is an extensible wiki with an extensible ...

This is the approach I'm currently exploring.  The "plugins" will be
implemented via Getlets (or some such), so that their implementation
is not restricted to a particular language, tool set, etc.

It will be interesting, however, to see what limitations turn up (eg,
can it do AJAX?) and how hard it will be to fashion workarounds, etc.


> And human constraints make this natural.  However nothing stops you
> from having a wiki that is backed by a source control system.

In the short term, my own resource limitations (eg, development time)
will prevent this.  In the longer term, it is quite possible.


> Furthermore if you add a conflict resolution system, then the web-
> based interface could update only the wiki part of the project,
> but the wiki could be part of the actual source tree that
> programmers work with.

I have actually played with putting source code pages in a wiki, with
the idea of letting a daemon process them into sets of web pages.  My
impression, however, is that the wiki is not a good way to edit large
blocks of code.  So, for now, I'm editing offline.  However, I suspect
that some hybrid approach (possibly based on uploads) might work.


> This allows programmers to synchronize documentation checkins with
> the associated code, yet lets external users make their own comments.

MediaWiki provides a "discussion" page for every base page.  Users can
edit these to comment about base pages, etc.  MW also allows "template"
pages which can be "transcluded" into other pages.  This allows users
to edit the base page, while leaving the exact content of the template
(read, mechanically-generated content) alone.


> You need to draw the line between what is done mechanically ...
> In general the more control you add, the more difficult ...
> ...
> Leaving the option of making some data slower to refresh is an
> important system optimization in some circumstances.
> ...
> That's the beauty of autogenerated stubs.  It is obvious that ...

Yep.


> Oh, and if the wiki is backed by a source control system as I
> suggested, then we add my top desire - the documentation can easily
> ship with the source code. :-)

Well, that's certainly a very strong priority.  More to the point, the
documentation _system_ should ship with the source code, so that some
developer in the field can make changes and see the results locally.


FWIW, my own efforts are currently centered on devising ontology-based
techniques that can be integrated with MW.  To this end, I'm creating
a naive Unix ontology (as a set of YAML files) and using it to populate
a "sandbox" wiki (http://www.cfcl.com/rdm/mediawiki/index.php/AC_Index)
with some "abstract classes" (eg, directory, user execute access).

Feel free to look around, but bear in mind that these are baby steps!
In particular, note that the ontology is only about 15% entered (much
less tested) and that I haven't set up diagram generation, etc.  That
said, comments and questions are welcome...

-r
-- 
http://www.cfcl.com/rdm            Rich Morin
http://www.cfcl.com/rdm/resume     rdm@cfcl.com
http://www.cfcl.com/rdm/weblog     +1 650-873-7841

Technical editing and writing, programming, and web development