Script Only Stack Architecture
ambassador at fourthworld.com
Fri Apr 1 03:43:41 CEST 2016
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
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
"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
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
> 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
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
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
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
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
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. :)
Fourth World Systems
Software Design and Development for the Desktop, Mobile, and the Web
Ambassador at FourthWorld.com http://www.FourthWorld.com
More information about the use-livecode