Subject: Re: mechanised documentation and my business model solution
From: Brian Behlendorf <brian@collab.net>
Date: Mon, 27 Mar 2006 09:30:55 -0800 (PST)

On Sun, 26 Mar 2006, Rich Morin wrote:
> For example, TWiki (a file-based wiki) keeps its files in
> RCS.  This solves part of the versioning problem, but not
> all of it.  CVS or Subversion would certainly solve other
> issues, if either could be shoe-horned in.  In any case,
> we've exceeded both my interest and expertise.

There's at least two wiki tools backed by SVN:

http://subwiki.tigris.org/
http://cgi.afc.no-ip.info/svnwiki.cgi/default/svnwiki

I'm a strong believer, though, that content specific to code should be 
built and versioned next to the code.  The ease-of-editing and 
anyone-can-do-it aspects that make Wikis popular is less about technology 
and more about policy, the policy that usually has source code managed 
using command-line or IDE tools and has commit privileges limited to just 
a few trusted people, leaving others to propose changes in the form of 
patches to a mailing list (laborious, long feedback loop).  I'll note that 
as Wikis become more common, people start reinventing wheels, like tagged 
versioning, transactional commits across multiple pages, limited commit 
privs, and proposing changes on mailing lists/web boards.

I suggest the answer lies less in using some alternative tool just for 
documentation (severing ties between docs and code) and instead adjusting 
the developer tools for the use cases that people love about Wikis.  What 
if the standard web viewer for CVS and SVN trees, ViewVC:

http://viewvc.tigris.org/

...was adapted to be read/write rather than read-only, with a set of pages 
maintained using some sort of Wiki syntax (which could be edited through 
ViewVC or through other editing tools), with commit privs to those pages 
or others granted more widely than those granted to developers on the 
source code.

I also feel that proper, searchable archives of mailing lists often serve 
as a better knowlegebase than a Wiki associated with a project, simply 
because there is zero effort required to turn that into useful data, 
versus the effort required to encode that information into a Wiki. 
The reason we have Google rather than Xanadu is that creating structured 
data is much harder (per value received) than sorting and filtering 
unstructured data.  I realize people can post questions on a Wiki, but 
that just seems... odd.  I can't keep up with changes to a Wiki (where I'd 
notice, as a Wiki maintainer, the question being asked) as if it were a 
discussion forum.  It just feels like a hammer/everything-is-a-nail 
problem.

 	Brian