Overhauling the Documentation for Director

Question

Hi Everyone,
Please excuse this cross-post. You can also find it on the Direct-L mailing list and on the Director Online Forum. I will post a summary of answers to each of these places.
Rajnish Bharti, Product Manager for Director and Shockwave, asked me last week for my input on how best to overhaul the documentation for Director.  In particular, he asked me to give him an idea of what the Table of Contents should look like.
You can find my first draft of the Table of Contents here:
http://www.openspark.com/adobe/Director_Documentation_01.zip
While preparing this, I contacted a number of Director teachers and trainers, talked to some newcomers to Director, consulted dozens of Director books (mostly from the Macromedia days) and pored over the various reincarnations of Director's own help.
Examples
Lots of real-life examples that you can copy and paste and
know that they will work
Images
Clear and concise screen shots that capture the essence of
a concept at a glance
Fast and Powerful Searching
Beginners don't know which menu item or scripting term they
are looking for.  The search engine should help users to home
in from a layman's expression to the appropriate documentation
article.  Articles should be intelligently cross-referenced.
I have suggested dividing the documentation into three sections:
1. Director Step by Step
A series of short hands-on tutorials which introduce all the
commonly-used features of Director in the context of simple
movies.  Beginners can start here.
This section imagines that you have never used Director or
studied its documentation before.  You select a project that
is similar to the one you are planning, and the documentation
shows you how to achieve your goal using Director.
Hyperlinks lead you to more in-depth entries in the Feature
Guide on how a feature works, or to the appropriate entry in
the Scripting Dictionary.
2. Feature Guide
This section will give detailed explanations of each feature,
category by category.  It will be divided into three main
chapters:
The Workspace
Working with the various windows and menus
The Raw Materials
Understanding sprites, members, the various media types
and data types
The Process
Designing your project, animating sprites, using scripts
and publishing your work.
This section will give you a categorized view of what Director
does.  It imagines that you start with a "How do I..." type of
question, and guides you to the appropriate part of the
User Interface or the correct scripting terms to use.
It will contain links both to the Step by Step tutorials and
to the entries in the Lingo Dictionary.
3. Alphabetical Scripting Dictionary
I have abandoned the idea of having the Dictionary divided
into categories.  I believe it is much easier to find an
entry without having to wonder whether it is a keyword, a
method or an operator.  If you don't know what entry you
should be looking for, the Feature Guide will help you.  If
you do know the word you are looking for, then you only
need to know the alphabet.
Each entry in the Scripting Dictionary should link back to
the articles in the Feature Guide which refer to it, and to
each of the tutorials in the Step by Step section which use
the term.
I also suggest (Section 4) implementing a much more powerful Search engine than the D11.5 browser-based help currently features, but that is not really a part of the Table of Contents.
The document that I have posted at...
http://www.openspark.com/adobe/Director_Documentation_01.zip
... is by no means definitive, but it is at a point where I am ready to share it, to check if my general approach is acceptable.
I have not gone into much greater detail in some areas than in others, so past the 4th level, you may find certain areas are still vague.  You may have better ideas for the Step by Step tutorial movies than the ones I have included.
Red text indicates new content.
I welcome feedback from all members on the community, both in terms of the content and the structure.
Once we have a comprehensive list of all the topics to cover and a consensus on the structure, then we will have to work out the most cost-effective way of generating the actual content.
Let me know what you think,
James

Answer 1

James, this looks outstanding!
I'm too far behind in versions to offer much here, but one thing I noticed that, I think is an oops:
3.4.    Java Dictionary
should be:
3.4.    JavaScript Dictionary
Unless they brought back the Java beast, that is.
Mark A. Boyd
Keep-On-Learnin' :-)