Revdocs on a wiki

[Judy Perry]

This sort of goes to the heart of why I think that a well-done book,
complete with a good index and a plethora of commented code snippets,
would be invaluable as opposed to any sort of online analog.

The main point is this:  people already know how to use books.  In all the
years since the 1460s invention of the printing press, but especially in
the last 150 years or so, we've codified the format of the printed book in
terms of the table of contents, glossary, index, and usage of headers and
footers.  I'd guess that there's scarcely a semi-literate adult who's
unable to use descriptive, functional and locational terms to describe a
TOC, a glossary, an index (heck, even my students can do it!).

But these things are either not standardized in online formats or absent
altogether.  You're new to the environment, and, looking to leverage your
existing (programming?) knowledge, you type in some technical term which
does not exist in Transcript.  What do you get?

Nothing.

That's not helpful.  In a printed book with a well-done index, if there
was an expectation that the readership of the book might well be looking
for that term, you'd get the following:

GeekyC++thingy-- see CorrespondingNotSoGeekyTranscriptThingy.

Which is worlds more helpful than a "not found" message, because "not
found" makes people feel stupid, people don't like to feel stupid, and
they especially don't like *paying* to feel stupid (well, okay, clearly
_I_ don't mind so much looking stupid).

I just received via interlibrary loan a book on one of my medieval history
interests.  It was published in 1982.  And the *&^%! thing doesn't have a
*&(%! index!!!  It  makes me want to hunt down the author and throttle
him!

Has anyone on this list a well-thumbed programming-related book?  Did you
scribble in the margins?  Hilight text? Bookmark pages with stickies,
paperclips, or by bending back the pages to mark them?  Read it in bed/at
the bus stop/while outside watching your kids?  How many of these things
can be done with any online documentation strategy?

And that's without bozos like me going in and running amok with your
wikis.

And, for the newbies wondering "what is a button?", imagine how they feel
when a tabbed control looks and acts like a set of buttons, only you can't
disable their contents so obviously because, as someone will inevitably
tell you, "you know, they're really not buttons; they're menus".

And we're back to feeling stupid again.

Judy

> >On Oct 27, 2005, at 8:29 PM, Timothy Miller wrote:
> >
> In an off-list exchange with one of the subscribers, I got the
> impression that most of the list subscribers are lurkers, and most of
> the lurkers are newbies. He/she said, "I wish the newbies would ask
> really basic questions more often, like, 'What is a button?'"
>
> When I taught myself hyperCard, I literally started with "What is a
> button?" Double-clicking on the button really made me nervous. Then
> it was, "What is a script?" It was slow going for me. I struggled
> with if - else - end for a week before I could use them effectively.
> I hardly knew what the internet was, back then. I didn't have access.
> But with Danny Goodman's book in one hand, the keyboard in the other,
> I figured it out. Many thousands (how many, really, I wonder?
> Millions, maybe?) did the same thing. Danny Goodman's book was rather
> expensive, and I had to buy at least one revision, maybe two. That
> was a serious barrier to me.
>
> (I should add, learning HC was easier for me than it would have been
> for most newbies. I had taught myself Basic, a few years before, on
> my Atari 64, and actually wrote a rather complex application.)
>
> Do we all agree that it's harder to teach oneself Dreamcard, not to
> mention Revolution, than it was with HC? And now there's no Danny
> Goodman book. (But everyone should buy Dan's book!)
>
> A hyperlinked indexed reference of some kind would probably be more
> comfortable and effective than Danny Goodman's book was. That wasn't
> technically possible at the time. It is now.
>
> It seems possible that such an electronic reference could be equally
> attractive and effective for a big range of users, from
> "What-is-a-button?" types, all the way up to seasoned developers.
> Good as the new version of Rev's docs might be, it's hard to imagine
> that they could optimally address the needs of such a broad spectrum
> of users.
>
> I know little about the Runtime Revolution company, or its prospects,
> except I sometimes hear it's short on resources. And I've gotten the
> impression that Rev is not catching on as fast as early enthusiasts
> had hoped. Doesn't Rev need to become loved and needed by hundreds of
> thousands of really green new users, if it is to survive and prosper?
>
>
> Nuff said.