docWikis

[Timothy Miller]

It suddenly occurs to me that the docWiki issue goes far beyond 
Revolution, though it's possible that Rev could be the first software 
company to take full advantage of the opportunity. As others have 
mentioned, Rev is a great platform for a comprehensive and 
frequently-upgradeable help system.

For instance...

The help files on my OS 10.3.9 Macintosh are okay, compared to 
previous incarnations of the Macintosh, and compared to the help 
files on Windows XP, frinstance. Compared to what the Macintosh 
onboard docs *could* be, given lots of generous, loyal, knowledgeable 
users, a very small team of editors, a wiki, and a few tech tricks, 
they are a disgraceful disgrace!

Why should I have to spend precious minutes--or hours--hunting on the 
Apple support site for a technical bulletin that I hope will explain 
why my modem won't send faxes, and how to make it work? If other 
users have had the same problem, and solved it, one of them would 
donate the needed information to the Macintosh docWiki, in clear 
English, plus maybe a link to the technical bulletin.

The editors could check it for accuracy, add some "related links" 
index it and cross-reference it, release it to their public docWiki, 
and at the same time, release it to the next generation of indexed, 
cross-referenced help docs, ready for download, or update, or 
whatever. The topics could -- and maybe should -- be searchable in 
several different ways -- filter, search-for, logic-tree, FAQs by 
topic and subtopic, etc. Maybe boolean, too.

Such docs could -- and maybe should -- be updated frequently, maybe 
every day, and eligible for automatic updating, should the user 
desire it.

In the same way, docWiki users could suggest clearer wording on 
topics already in use, novice, intermediate, and expert versions of 
the same topic, terse or verbose versions, and so on. Some topics 
would be specific to one machine model, OS version, or software 
version. Users of one machine, or one software version, ideally, 
could download only the information necessary for the software, the 
machine and the OS they actually use, though public docWikis would 
remain available for other versions, other machines, and so on.

The examples go on forever. Why should the same weary volunteer 
experts -- on newsgroups and help boards -- answer the same 200 or 
300 questions over and over and over again? For such questions, all 
that is needed would be a link to the right page on the wiki or the 
right page in the onboard help documentation. That would leave the 
volunteer gurus free to field the relatively few new, significant 
questions. Once solved, those issues would also go to the docWiki. 
And so on.

Onboard help files could and should be integrated in such a way that 
help documentation from various sources could be merged for indexing 
and retrieval-- yet tracked separately, so they could be deleted or 
updated separately, if needed. Like if I upgrade to a newer version 
of PageSpinner, for instance, the onboard docs for PageSpinner would 
be refreshed at the same time, without disrupting anything else.

Macintosh already does something along these lines. But the 
documentation is so thin... Any time I have a slightly unusual or 
complex issue, I can be pretty certain the answer I need will *not* 
be in the onboard help docs.

I'm not talking about just Apple or Windows. Every application, 
programming language, specific machine, etc., would all benefit from 
this approach. The thing that makes me crazy about this, when I think 
about it, is that it just wouldn't be very difficult, or expensive, 
for any manufacturer or developer to participate.

Some kind of open standard for onboard and/or online help would be 
very helpful, of course. God knows we don't want Bill Gates to choose 
the standard!

When I think about it this way, Rev is already doing a very good job 
of indexing its onboard documentation, with plenty of hyperlinks, 
"see also" links, scripting examples, and so on. Better than any 
other application I use. (I don't know about other development 
environments. Rev is the only one I use.)

All that's missing -- for Rev -- is more of same, plus a wiki, for 
continuous improvement and expansion, plus an editorial team, plus 
frequent downloadable updates.

Just a thought. A minor inspiration. I dunno -- maybe stupid -- maybe 
already thought of, or on the way. I'm not a computer professional.

Cheers,


Tim

>On 17 Oct 2005, at 12:45, Marielle Lange wrote:
>
>>Anybody to keep an eye on my wiki during that time
>
>Sure I know TikiWiki pretty well by now - can you give me admin 
>access so i can turn off those smileys :)
>
>>>I did find this 
>>>http://revolution.lexicall.org/wiki/tiki-index.php?page=SoftwareRevolution, 
>>>but felt that it wasn't quite what I was looking for.
>>
>>In what sense?
>>
>>These page are meant to serve exactly the same purpose  you propose.
>>http://revolution.lexicall.org/wiki/tiki-index.php?page=RevolutionSnippetTips
>>http://revolution.lexicall.org/wiki/tiki-index.php?page=ProgrammingXtalk
>>http://revolution.lexicall.org/wiki/tiki-index.php?page=TutorialsTeachers
>>
>>I agree, this is a bit burried down, there is too much content on 
>>this wiki...
>>
>>>So, I've set up a wiki at http://revdocwiki.wikispaces.org/ .
>
>Hmmm... three TikiWiki sites out there, and another wiki. Is it 
>really necessary to set up another site - setting up is easy 
>-maintenance another thing. Another example of the "revolutionary 
>approach" to collaboration perhaps :) Could we not all work on the 
>same wiki - said hopefully :)
>
>NB - having some regular crashes with XML parsing in 2.6.1. For 
>instance I can parse TikiWiki pages from www.openpartnership.net, 
>but testing on 
>http://revolution.lexicall.org/wiki/tiki-index.php?page=RevolutionSnippetTips 
>appears to crash Rev.
>
>Has anything changed?
>
>
>
>
>_______________________________________________
>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