Script Only Stack Architecture

[Matt Maier]

You keep citing the theoretically limitless number of contingencies that,
if addressed, could bloat the dictionary beyond readability. There's a
simple solution to that problem: don't go looking for theoretical problems.

Instead, just correct, massage, or add to the dictionary entry when someone
has a problem relevant to that entry.

I've also maintained gigantic technical references (fighter aircraft
weapons systems, satellite operations, and ground control systems) and we
followed that simple process. The TOs (technical orders) started out with
just the instructions from the factory. Over time they accumulated
corrections, warnings, cautions, and notes in response to actual events.
That way the extra information appeared right where it was needed and
nobody wasted time on any theoretically necessary information.

That's a big part of helping people learn on their own. Putting the
information they need right where they need it, rather than putting it
somewhere and challenging them to go find it.

On Thu, Mar 31, 2016 at 6:43 PM, Richard Gaskin <ambassador at fourthworld.com>
wrote:

> 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
>
>
> _______________________________________________
> use-livecode mailing list
> use-livecode at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-livecode
>