1 Reply Latest reply on Apr 13, 2009 6:23 PM by Mark A. Boyd

    Overhauling the Documentation for Director

    James Newton, ACP Level 3

      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