Revdocs on a wiki

[David Bovill]

100% Dennis - except I think you may have hit copy and paste by  
accident for points 2 and 3 :)

Could I propose that we use your post as "rough draft spec"? - and  
put it up on the wiki of course - which one is another matter :)


On 29 Oct 2005, at 19:11, Dennis Brown wrote:

> I am not interested in supporting a mish-mash unstructured free-for- 
> all of information.  That is not the point at all.  I like much of  
> the structure of the current embedded Rev documentation.  The  
> dictionary is immeasurably useful.  It is even more useful when  
> integrated into the script editor as done in Constellation.  Web  
> notes could have been useful --if it actually worked.
>
> However, if RunRev were to just make a wiki available and say have  
> at it, I would fear eminent failure.
>
> What I envision, is a well structured database of information that  
> is not only useful to newbie and professional, but allows for  
> upgrading the information without waiting for an annual formal  
> release cycle.  We can call it a wiki, but I think it has to be  
> better than the average wiki.  Not only does it need to better than  
> a typical wiki, it also needs to do things that a book can not do.
>
> Some of the things I would like to see:
>
> 1.  A single consensus wish list from user the community for RunRev  
> to see --call it a rough draft spec
> 2.  A single consensus wish list from user the community for RunRev  
> to see --call it a rough draft spec
> 3.  A single consensus wish list from user the community for RunRev  
> to see --call it a rough draft spec
>
> 4.  Article change/delete by voting members --three strikes and you  
> are out --or in
> 5.  Discussion about potential changes occur on the use-rev list as  
> it does now
> 6.  Articles included or pointers to articles with attributions and  
> pointers to "about the author" --like in the tutorial stacks
> 7.  Rev front end to integrate the site into tools (not browser  
> dependent unless a pointer takes you to another web site)
> 8.  Starting page of link lists of your interest:
>     a.  Learning Transcript --takes you to the next index page of  
> topics (linear links take you from topic to topic inside an  
> article, branches to download tutorials from other sites)
>     b.  Language Dictionary --takes you to category index page  
> (search always available)
>     c.  How Do I --takes you to a category index where you drill  
> down to ever more concise areas, then finally to a list of example/ 
> discussions
>     d.  Tools available to developers
>     e.  Scripting styles
>     f.  Other resources
>     g...
>
> As you can see, I look at this as a way of organizing the existing  
> information and resources in one place.  I see it as fulfilling  
> several major needs:
> 1.  That wonderful TOC and Index to the great information available  
> (along with the hyperlinks that only an electronic book can have)
> 2.  A place to deposit many of the jewels of information that come  
> from the use-rev list where they can be easily found by the  
> inquiring mind
> 3.  Visibility for rev developers and web sites that is linked  
> directly to the needs of the user --by virtue of were they are looking
>
> Having the backing of RunRev for this project significantly  
> increases the odds of success (from 40% to 80%), even if they  
> provided nothing more than acknowledging it on their home page as  
> the place to go to learn.