Revdocs on a wiki

[Jim Ault]

On 10/28/05 7:31 PM, "Judy Perry" <jperryl at ecs.fullerton.edu> wrote:

> 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.

Actually, only one comment about printed tech books.. they are usually
processed through the marketing/publishing machine and so the main body of
work may be great and a few illustrations mislabeled or misplaced, BUT...
<peeve>
My biggest pet peeve is the indexing.  Either...
1. The word I am trying to find is not there, and any synonym is a dead end
2. The word is there, but it is a sub-listing so you have to read the whole
index to find it
3. The editor's use of the word is not how you would use it
4. Eureka!  it is here, but the page numbers don't have the word on them
anywhere.
5. Eureka!  it is here, but all the citations discuss something other than
the context you need.

I would love it if they included a thesaurus to the index. (in case you
could not tell, I just went through this last night in books and on the web
related to Applescript)
</peeve>
I think this is the rationale for the 'recipes' in the docs.
Some web sites are such that the links take you through a sequence that is
logical, bite-sized, and printable.  Perhaps the wiki could have long,
gentle newbie paths and also short cuts for the same material.

Jim Ault
Las Vegas

On 10/28/05 7:31 PM, "Judy Perry" <jperryl at ecs.fullerton.edu> wrote:

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