Script Only Stack Architecture

[Richard Gaskin]

Matt Maier wrote:

 > I just want to chime in to disagree with the idea that we should leave
 > useful information out of the Dictionary.

When you put it like that it sounds silly indeed.  Fortunately I wasn't 
advocating omitting useful information, just suggesting we may want to 
maintain an awareness for the scope of doc options at our disposal, and 
be mindful about which details go where.

If you were advocating silliness we might put the User Guide, the 
Lessons, and every LiveCode blog into the Dictionary.  But I know you're 
not.

We want useful information, where it's most useful.


 > There's no such thing as a document that's too big when we have
 > networks and search.

That's precisely why I advocate maintaining the Dictionary as an 
essential reference (as in "essence"); it should be easy to link to 
relevant tutorials and guides for more complete discussion when desired.


 > If it takes a while to explain, then it takes a while to explain.

One of the products I work in is a medial reference for pediatric 
emergency specialists.  Much of its info is in the Physician's Desk 
Reference and a large number of current research papers, but what 
distinguishes our product is that it has LESS information than other 
available sources.

"What's that?  Less?"

Yes.  The PDR is too big to read.  Every doctor has it; few open it. 
And the wealth of information at PubMed is too vast to sift through when 
you have an ER case load stacked up.

So our team is comprised of ER specialists from around the world who 
gather the best information on modern practice available, and work 
diligently to distill it to its most valuable essence useful in a 
clinical setting.

The LiveCode Dictionary need not be quite as sparse; no one's dying on 
an ER table waiting for us to find the parameters to "import snapshot" 
(and God help them if they were <g>).

But there are different forms of docs because each serves a different 
purpose.


 > If there are a lot of caveats, then there are a lot of caveats.
 > That sounds like a good reason to simplify the application, not
 > a good reason to keep secrets.

Simplifying the app is indeed the first goal.  Mark Waddingham has 
already slated behavior resolution for cleanup, so it will become 
simpler at some point in the future.

But in the here and now, rest assured there's no conspiracy to keep 
anything secret.

The question on the table is: what is most appropriate in the 
Dictionary, and what is most appropriate for another resource?

The Dictionary is not a User Guide, nor a tutorial.  It's a reference 
for understanding what an API token expects, and what will be returned.

There are many caveats throughout the Dictionary, and arguably there 
should be more.

But I would caution against turning it into the most comprehensive 
collection of all possible things one might mistakenly do and how to 
avoid them.  Each page could be 1MB or more with just mistakes I've made 
alone. :)

In this specific case, a key part of the original confusion resulted not 
from something missing from the "behavior" entry, but by not consulting 
the "start using" entry.  I've been teaching xTalks for decades, and 
that's one mismatch I'd not previously encountered.  In retrospect it's 
understandable, and I won't completely rule out the possibility that a 
note about "start using" not being relevant to "behavior" may be worth 
putting in.

But so many things aren't relevant to so many others, it seems more 
helpful to guide the user to the things that are.  Rather than talk 
their ear off with entries longer than my posts here about all the 
possible ways things might go wrong, it seems simpler and more 
respectful of their time to just show them the way to do things right 
and let them enjoy success and move on.


 > What feels like a "hefty tome" to someone with decades of experience
 > feels like a "gold mine" to someone with no experience. A lot of gold
 > is heavy; that's just how it works.

Agreed.  Some of the best reading I've had is with technical specs.

I believe in-depth discussion of collections of related concepts are 
best handled in User Guides.

The Dictionary serves a more specialized role.

Tutorials serve yet another role.

All are important.  And each distinct.

And we have to face an important consideration with all learning 
materials in all fields of human endeavor:  no matter how complete, no 
matter how well written, only part of it will be read, and mistakes will 
be made.

Learning happens only in a small way from reading.  The greatest depth 
and retention occurs through hands-on practice.  And the nature of 
practice means making mistakes, understanding the nature of the specific 
mistake made, and correcting it.  You can read about a piano all day 
long, and never understand as much about it as an hour at the keyboard. 
  Similarly, I believe interactive media is best learned through 
interaction.

Not that we shouldn't aim high with the docs.  But it's important to 
remember that the sum of all documentation is only a small part of how 
people learn; that's just how it works. :)

-- 
  Richard Gaskin
  Fourth World Systems
  Software Design and Development for the Desktop, Mobile, and the Web
  ____________________________________________________________________
  Ambassador at FourthWorld.com                http://www.FourthWorld.com