how to disturb newbies

[Richard Gaskin]

Jeff Reynolds hit on some excellent points here:

 > One thing also with documentation like the, and newbies are the
 > most vulnerable to this, is how well written it is and does it
 > cover all the steps (ie not start c, d, e...). It hard for a high
 > end development crew to hopefully have the ability to write and
 > edit to a very clean and readable style and also not take some of
 > the very basic knowledge for granted.
...
 > I'm not saying at all the rev dictionary is poorly written at all.
 > I have always found it very good for me for the most part (more
 > info would always be great and a notes function useful as well)

Reading this in mind with the instances where folks have complained 
about not being able to find what they're looking for, two thoughts emerge:

1. Tagging or other searchability enhancement is paramount.
Too many times we know what we want to do, and need to find the token to 
accomplish it.  For example, you're looking for how to purge a stack 
from memory when it closes with no interest at all in destroying it in 
any way, not even the hundredth monkey could be expected to stumble 
across it by typing in "destroyStack".  Tagging, free-text, or other 
enhanced search would do wonders with that.

2. Most folks agree with the assessment here, that while it may be nice 
to see some more compete end-to-end examples, by and large they can get 
what they need from the content (when they can find it), provided they 
have enough basic background in how LiveCode works to see how the parts fit.

One of the challenges with attempting end-to-end examples for many of 
the language elements is that they're very, very flexible.  How many 
different examples would be need for binaryEncode, or ReplaceText, or 
even just customPropertySets before we could expect the Dictionary to be 
a one-stop solution.

So maybe it can't.

And since little if any of the User Guide is read, maybe what's needed 
is a truly essential "Getting Started" guide, with just the barest bones 
possible to orient a newcomer to get started, only compete enough for 
that orientation but not a word longer so that it would actually be read.

What info should be included in such a Guide?


On this:

 > Just saying if you really want the more average user and newbie to
 > really grock the material that nuance of a professional giving all
 > the content a good pass really can help and it tends to be the last
 > priority unfortunately.

Absolutely.  And with some 90% of users running the Community Edition, I 
think it's safe to suggest that an effort of that magnitude would only 
be accomplishable with the support of the community.

Anyone up for participating in a Dictionary triage and revision please 
drop me a note and we'll make this happen one way or another.

-- 
  Richard Gaskin
  LiveCode Community Manager
  richard at livecode.org