Field calculations

[Richard Gaskin]

Vaughn Clement wrote:

> As trainers yourself you must recognize this in the fragmented approach
> being used to present instructional materials from LiveCode.

Of course, but I wear multiple hats:

As a business owner I recognize the cost of developing such 
comprehensive documentation.

While some languages may do well with their docs, most that the best of 
them still rely on third-party documentation -- O'Reilly has built an 
empire from providing supplemental documentation for the world's most 
popular languages, while neither Adobe, Apple, Oracle, Asymetrix, nor 
most of the others who've ever delivered a proprietary scripting 
language have exceeded (nor in some cases not even come close to 
matching) to what's in LC, for better or worse.

In fact, the most comprehensive docs I've ever seen for any language 
were for Gain Momentum, an xTalk originally published by Sybase, whose 
collection of volumes stacked literally two feet high.  Wonderful 
effort, but it contributed to the product's lack of profit, ultimately 
prompting Sybase to sell it off.  The new owners put most of their 
resources into supporting new platforms and features, and the 
documentation for Gain today isn't anywhere near as comprehensive as it 
used to ship with.

Good docs are indeed valuable, but expensive.


Which leads me to another had I wear:  open source community member.

I've contributed to a few other FOSS projects, and welcome the 
opportunity to contribute to LC as well.

While the cost to a single resource for providing such comprehensive 
documentation would be very expensive, the same could be said for 
kernels and window managers and everything else communities have 
delivered well by spreading the load among multiple resources.

I agree that it would be ideal if RunRev could assign a team to expand 
the docs as outlined, but these other two hats I wear lead me to look 
for solutions which can leverage existing resources.


Which leads me right back to the first hat you mentioned:  LiveCode 
training consultant.

No, not in the cynical sense of "as long as it's hard to grok I have job 
security", but in the sense of having spent a lot of time with people 
over the years to appreciate the unusually broad range of needs that 
come into play with a tool like LiveCode.

When folks pick up a C compiler, they expect it to be hard, but LC is 
useful to people who don't see themselves as programmers; many have no 
background in programming at all, and they're rightfully much more 
demanding.

Many segments of the LC audience have very different needs.

At one extreme, some of us managed to muddle through well enough long 
before LC was born, with a much sparser MetaCard dictionary and without 
the User Guide, Lessons, Tutorials, Online Conferences, examples, and 
other things we enjoy today.

On the other extreme, a good many future users will need even more than 
you're asking for, since they're coming from a much less experienced 
background.

The audience for LC is uncommonly broad, so truly great docs for 
everyone it attracts is quite an undertaking, profoundly expensive when 
we consider the range of things like search synonyms and widely varying 
complete end-to-end examples needed to make them optimal.  Each user 
brings a different set of preconceptions and use-case needs to the IDE; 
truly great docs will have to accommodate at least a majority of them, 
and that will cost thousands of hours to produce.


So stacking all these hats on top of my arguably thick skull, in brief:

- As a business owner I recognize the challenge of producing good docs.
- As a FOSS contributor I recognize the value of crowdsourcing.
- As a LiveCode trainer I recognize that the scope of needs here is 
unusually broad.

I don't work for RunRev, so I'm not in a position to demand that they 
drop their work on resolution independence or any other features until 
the docs are truly exemplary; absent infinite budgets, every investment 
in any business is about such trade-offs.

All I can do is roll up my sleeves to help, contributing to this list, 
the forums, and the IDE development.

The comments make a reasonably good starting point because:

1. They allow individual to contribute their own unique experience to 
the docs, something no single individual can anticipate.

2. They exist today.

3. They serve as a foundation which can be invaluable in informing later 
documentation enhancements from RunRev as time and budget permit.

--
  Richard Gaskin
  Fourth World
  LiveCode training and consulting: http://www.fourthworld.com
  Webzine for LiveCode developers: http://www.LiveCodeJournal.com
  Follow me on Twitter:  http://twitter.com/FourthWorldSys