Documentation & Books & related

[Judy Perry]

And, what I suspect someone is going to note next (if not previously),
Marian, is, "well, did you take a look at user contributions at Rev's
website?"

Here's why that's not a good answer:

People who lack confidence in their abilities to program/use Rev are going
to be overwhelmed.  Their assumption is that anything important is going
to be up front and visible and in the docs.  Telling them to essentially
go search the web is going to turn them off because it's almost like
telling them they're stupid as they didn't know previously that if you
don't find something in the docs, your next step is to go here, then
there, then someplace else.  They're kinda like Buttercup, my chihuahua:
even as a puppy (and still now as a 10-yr. old dog), she liked boundaries
to her universe.  They make her feel secure and confident.

Think back to the guy with the tabbed buttons problem.  The average
"novice" wouldn't have kept at it for five or six posts to the list to get
his question answered.  He kept at it because  he had the confidence of
prior programming experience to know that there HAD to be an answer and
that perhaps the problem was one of properly expressing his problem/wish.
A novice won't do that because they don't want to feel stupid; don't want
to think that people are thinking that they're stupid.

Of course, this gets back to whether you can be all things to all people.
This is what I think made the HC UI a wonderful model: when you opened it
up, right up front and visible were things like the sample buttons stack
and the like.  And the downside to this is perhaps that a seasoned
programmer looks at this and thinks, "what an amateurish thing this is;
obviously can't do any real programming with it..."

:(

Judy

On Wed, 7 Jul 2004, Marian Petrides wrote:

> I'd like especially to highlight one of Alex's suggestions:
>
>  >>> Provide a larger set of samples. The Recipes are good - but more of
> them, and a few more which show complete (even if tiny) examples. Right
> now, it's too easy to get a recipe which shows you the one line you
> need to use - but doesn't help you with context.
>
> Think of the things someone just starting out will need to know and
> give them to him in "words of one phoneme." It is very difficult for
> someone who "speaks the language" to remember what it was like when
> they couldn't.  This is true whether you are teaching medicine or
> teaching Rev.  And YES, you DO have to teach (Dan's comment about
> digging for pearls notwithstanding), cuz (deliberate bad spelling) if
> you don't,  you will continue to have people turning away in
> frustration.  Lost revenue, but, more importantly, lost user base. It's
> time to build critical mass guys and gals.