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 ~ [EMAIL PROTECTED] http://www.jaedworks.com _______________________________________________ use-revolution mailing list use-revolution@lists.runrev.com Please visit this url to subscribe, unsubscribe and manage your subscription preferences: http://lists.runrev.com/mailman/listinfo/use-revolution
