Subject: Re: mechanised documentation and my business model solution
From: "Stephen J. Turnbull" <turnbull@sk.tsukuba.ac.jp>
Date: Sun, 26 Mar 2006 00:54:47 +0900

>>>>> "Rich" == Rich Morin <rdm@cfcl.com> writes:

    >> If you don't like the way a Wiki is organized, then reorganize
    >> it.

    Rich> Re-organizing an existing wiki that someone else has created
    Rich> is a quick way to make enemies.

Starting with your own wrists.  :-)

I think that existing wikis are fundamentally flawed as a
documentation vehicle, with the following three deficiencies being
prominent (but not necessarily in this order of importance):

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

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?)

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.

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.


-- 
Graduate School of Systems and Information Engineering   University of Tsukuba
http://turnbull.sk.tsukuba.ac.jp/        Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
        Economics of Information Communication and Computation Systems
          Experimental Economics, Microeconomic Theory, Game Theory