docWikis

[Jim Ault]

Of course, who decides what qualifies as good/excellent content..  Expert
level, moderate, beginner, one example, two, five, .. fastest algorithm,
easiest to write..  how to put pieces together to solve scenarios.. catalog
the exceptions and bugs.. even to build a rudimentary decision tree for
someone to follow to build an app..

All would be a very large task for several individuals.  Add to the mix that
the most accomplished contributors are advanced because they do this for a
living which means they have no time for their own documentation of
projects, let alone building a knowledge base.

In our little corner of the programming universe, I think that most anyone
only has time to skim, collect some valuable tidbits, contribute answers as
time and mood permit, then go on with our lives.

As they say, "managing programmers is like herding cats", and that is the
way it should be.  I wish you good luck getting support.  If I decided to
follow this path and contribute, my wife would kill me.

Jim Ault
Las Vegas


On 10/17/05 5:09 PM, "Timothy Miller" <gandalf at doctorTimothyMiller.com>
wrote:

> 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=RevolutionSnippetTip>>>
s
>>> 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
> 
> _______________________________________________
> 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