Revdocs on a wiki

MisterX b.xavier at internet.lu
Fri Oct 28 00:25:39 EDT 2005


Chipp

im working on something with TAOO as the front end for a better
Documentation platform which will import XML and export to HTML,
tiki ml and more... 

But nothing that's in a hurry due to heavy housekeeping ;)

cheers
Xavier
http://monsieurx.com/taoo 

> -----Original Message-----
> From: use-revolution-bounces at lists.runrev.com 
> [mailto:use-revolution-bounces at lists.runrev.com] On Behalf Of 
> Chipp Walters
> Sent: Friday, October 28, 2005 5:48 AM
> To: How to use Revolution
> Subject: Re: Revdocs on a wiki
> 
> Timothy Miller wrote:
> 
> 
> > The engineering team must certainly begin the documentation 
> process. 
> > If it's a simple application, then maybe the docs written by the 
> > engineers are as good as they can be.
> > 
> > But if it's a very complex application, or development tool, or 
> > whatever, then the documentation is *never* optimal.
> > 
> > If the engineering department had unlimited resources, and 
> the desire 
> > to engage in continuous quality improvement, then they would likely 
> > write better documentation than users on a wiki.
> > 
> > But no engineering department has unlimited resources. Beyond that, 
> > continuous quality improvement on documentation is an infinite task 
> > that would not appeal to many engineers. Writing more than 
> one version 
> > of the same entry, adjusting to the sophistication of the user -- I 
> > don't think many engineers would like that.
> 
> Tim,
> 
> You might want to reread what Dan was 'ranting' about. He's 
> talking about professional writers, not engineers. Jeanne 
> DeVoto (the original revDocs writers) and Dan Shafer are both 
> professional writers, each with multiple technical books and 
> manuals published. Back in the HyperCard days, they were both 
> well-published and well-read authors. I'm not sure I know 
> *any* engineers who can write as well.
> 
> Though, after seeing Sivakatirswami's post regarding PMwiki 
> and PDF's, I might be more inclined to consider a Rev backed 
> wiki experiment. The few wiki's I've been involved with in 
> the past were:
> 
> 1) Way too slow
> 2) Not well organized
> 3) Way too slow
> 4) Never really got to a finished state where they were really helpful
> 
> Did I mention how slow they were? :-)
> 
> But, with the dedicated users here on this list, and some 
> basic housekeeping rules (that means limited TAOO references 
> Xavier! ;-), it might be interesting to see what happens. 
> Perhaps with the shared enthusiasm, Kevin et al might 
> greenlight a test wiki.
> 
> Even if RR did, I suspect there would be a lot of time doing 
> front end analysis of how to organize the content so that it 
> can be reused. One of the good things about the docs in the 
> current XML state (not the doc viewer, but the underlying 
> data structure) is that it can be repurposed quickly. This is 
> great because many different users including Jerry Daniels, 
> Richard Gaskin, Wouter, Geoff Canyon and  myself have been 
> able to use the XML to create different ways at looking at 
> the documentation.
> 
> Some of these are free, others cost. But the beauty in XML is 
> that it doesn't 'lock' the content inside a display 
> presentation format. I assume wiki's can do the same thing.
> 
> best,
> 
> Chipp
> 
> _______________________________________________
> use-revolution mailing list
> use-revolution at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage 
> your subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-revolution




More information about the use-livecode mailing list