Rant Re Rev Documentation

[Jeanne A. E. DeVoto]

At 2:30 AM -0500 7/25/2005, Chipp Walters wrote:
>All good points. I agree. When I was just starting, many times the 
>'terse explanation' in the docs just didn't go far enough-- I wanted 
>a few more examples of how the transcript term was used. I talked 
>with Jeanne DeVoto about it (she *was* the author of most the 
>documentation, and IMO did a great job), and she told me to put in 
>explicit examples for all the terms would be a herculean effort 
>above the current resource allocation for it. So, I don't blame 
>her...or for that matter, RR.

I should also mention that in older versions of the docs, there was a 
"Cookbook" section (many of the items written by our own Jacque) with 
extended annotated examples of useful handlers, and linked to the 
dictionary via the See Also section. There weren't enough of these - 
fewer than a hundred, I think - but the plan was to grow them 
gradually until each dictionary word had a cookbook example or two 
where you could see how it was used. (It looks like the Cookbook was 
one of the things removed in the newer versions of the docs, though - 
don't want to have anyone wasting time digging for it. But you may be 
able to find it if you have an older version.) I agree that there 
need to be a lot more worked examples.

Writing the original documentation was, in many ways, triage: the 
most essential part was always the Dictionary, because without the 
language documentation you can't do anything at all. Then How Tos for 
the IDE and language, troubleshooting information, and basic 
navigation. Then conceptual overviews (the encyclopedia) and more 
extensive examples (the cookbook). Then everything else (graphics in 
the text, full index, extended navigation methods such as linear 
"tracks" through the docs for specific topics, documentation of 
windows in the IDE, still more examples, animated tutorials for 
beginners, and so on).

I used to tell Kevin that I could finish my plans for the docs, if he 
sent the development team to the beach for a year so I wouldn't have 
to research any new features and add the new material for them. ;-)
-- 
jeanne a. e. devoto ~ revolution at jaedworks.com
http://www.jaedworks.com