Documentation & Books

[Richard Gaskin]

James wrote:

 > Marian Petrides wrote:
 >
 >> Just because SOME people find it functional to use the online search
 >> function as an index, many others do not.
 >
 > For example any of us whose access to online services is still via a
 > dialup connection.

By "online" I believe Marian was referring to the docs included in the 
software, not anything requiring an Internet connection.

That this was not immediately recognized suggests that perhaps one the 
most critical tasks to improve the documentation would be making the 
Search Documentation tool more prominent.

A majority of the items reported here as MIA can be found with the 
Search Documentation tool using common terminology to describe them. 
Note that I didn't say "all", but cutting the number of unanswered 
questions by more than half in one move isn't bad.

For example, no one could expect a newcomer to guess that the way to 
purge a stack structure from memory would be to set its destroyStack 
property, but only 12 topics are returned when you search for "purge" 
and most are obviously not what you're looking for. Same with hunting 
down player volume control searching for "volume" and finding 
"playLoudness" among the 20 hits returned.

These search results are not much different from the entries you'll find 
in a good index, in which there are a good many entries for a given 
topic and you need to scan them to identify the ones that seem most 
likely to be related to what you're looking for.

As with their paper-based counterparts, you may need to check out a few 
different entries before you find the one that answers your question 
most fully. But with more than twice as much documentation as included 
with Director, ToolBook, and other more expensive tools, the answer 
you're looking for is very likely covered sufficiently to get you moving 
forward so long as you're willing to invest almost as much effort as you 
would expect to employ with a paper-based index (the electronic version 
is arguably a bit easier since going to an entry is just one click as 
opposed to thumbing through pages).

So maybe a useful question would be: How do we encourage folks to use 
the tools they have in hand now?

And again, talk of future possibilities aside, what was the question 
that prompted this thread?  Would the original poster like an answer?

-- 
  Richard Gaskin
  Fourth World Media Corporation
  ___________________________________________________________
  Ambassador at FourthWorld.com       http://www.FourthWorld.com