Subject: Re: mechanised documentation and my business model solution
From: Rich Morin <>
Date: Sat, 25 Mar 2006 09:06:56 -0800

At 12:54 AM +0900 3/26/06, Stephen J. Turnbull wrote:
> I think that existing wikis are fundamentally flawed as
> a documentation vehicle, ...

Many existing wikis are clearly unsuitable for this use.
For example, any wiki that isn't based on a DBMS is going
to be hard-pressed to handle versioning, etc.  However, I
think (hope :-) that useful exceptions can be found/built.

> 1)  The wiki information itself is versioned per page,
>     and can't be tagged for easy rollback across pages.

I think that the transaction facility of a DBMS could be
used to accomplish this, but I haven't seen any examples.

Before rushing off in this direction, however, let's ask
about the intended purpose.  If edits are happening on a
page-by-page basis, as in Wikipedia, when/why would you
want to do mass rollbacks?

If you're talking about mechanically-generated content,
I think there are other ways to handle this.  One way is
to re-generate the content.  Another (if the mechanically-
generated content is being incorporated dynamically) is
to have the server change the content it provides.

> 2)  Wikis don't support branching and conditional
>     generation of documents (so that you can have a
>     documentation "view" for the "bleeding edge", one
>     for the "stable line", and WIBNI you could *diff*
>     those two?)

Again, although I haven't seen any examples, I think that
a DBMS-backed wiki could handle this sort of thing.  The
hard problems, really, have to do with the user interface
(e.g., presentation, navigation).  How much support, for
example, should there be for allowing documents to span
versions, have exceptions for particular versions, etc.

I don't have any ready answers for these questions, but I
hasten to point out that non-wiki documentation systems
don't, either.  We're all just banging rocks together...

> 3)  Wikis are too free-format.  A team can write good
>     documentation, but even more so than good code there
>     must be a strong hand enforcing editorial style and
>     conventions.

This is mostly a cultural and political issue, with only
minor technical aspects.  Wikipedia wrestles with these
kinds of problems on a very large scale; most software
development projects have a much simpler situation...

> I've seen wikis used successfully for tutorial and howto
> material for smallish projects, and I've seen them used
> successfully as the main form of documentation where there
> is an active wiki wrangler/editor picking lint out of the
> wiki on a daily basis.  But with larger projects, even the
> howto pages tend to get duplicative, and it's hard to
> detect gaps.

I think this is a general problem with large sets of text.
Although it isn't totally soluble, an active wrangler/editor
can often keep the chaos largely under control.  The big win
with wikis, however, is that they encourage contributions.
Wrestling with chaotic material is far easier than having to
invent material from scratch!

MediaWiki (used by Wikipedia) has a couple of features that
help to keep things less chaotic.  First, each page has a
"shadow" discussion page, which can be used to propose new
content, argue about existing content, etc.  Second, a user
can ask to be notified about changes to a page.  This lets
the interested parties stay engaged, without forcing them to
"poll" the wiki.

Semantic MediaWiki promises to add "type" information to the
MW link syntax.  This could be used to allow users to make
very general notification requests (eg, any page covering
the FOO subsystem).  The semantic information will also be
useful for generating context and navigation diagrams, etc.

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development