Survey day: What docs do you use the most?

Hope you all had a nice and safe holiday.

Today is Tuesday survey day! Today I’d like to get your feedback on the areas where you use the Flash docs the most, and the areas where you’d like to see the most improvement, focus, examples, etc.

You might notice that the documentation is separated into books. If you go to the Flash Help panel and click the “Table of Contents” button, you can see their titles. Examples of the books are:

* Getting Started tutorials
* Using Flash
* Using ActionScript in Flash (the chaptery sections on ActionScript)
* ActionScript Language Reference (aka: dictionary)
* Using Components (which contains the Components Dictionary – please feel free to count that as a separate book!)
* Flash JavaScript Dictionary
* Data Tutorials

And ones after that are books that likely installed with your components.

Anyway, please consider the following for this survey:

* What book(s) do you use the most?
* Where would you personally like to see the “most improvement” or attention? (Maybe you don’t read a book now becuase it’s poor – but you would read it if it was good/improved).
* How do you use the books? (Ie: do you look for tutorials, code snippets, high-level workflow stuff, etc?)
* What are you: a developer, a designer, or a hybrid between the two – a deseloper?
* Any other feedback?

Thanks!

14 Responses to Survey day: What docs do you use the most?

  1. Aaron says:

    *I really almost exclusively use Actionscript language reference. Most of the rest I’ll come across occasionally in a search, but I primarily ignore.*I’d really like to see the “Using Components” section improved, primarily the sections on styling components which on some are nearly useless at this point.*I mostly use the actionscript dictionary, just as a reference for syntax.*I’d probably have to say a deseloper, I enjoy both sides of it to much to ignore either.*Um, well, enjoyed the survey, and I enjoy the blog, thanks!

  2. JesterXL says:

    * What book(s) do you use the most?Components Dictionary* Where would you personally like to see the “most improvement” or attention? (Maybe you don’t read a book now becuase it’s poor – but you would read it if it was good/improved).The metadata tag reference (refine + make more complete), collections example, and the styling of components.* How do you use the books? (Ie: do you look for tutorials, code snippets, high-level workflow stuff, etc?)I go to the components dictionary to remember/learn methods for components.I go to the ActionScript section to remember Flashcom methods.* What are you: a developer, a designer, or a hybrid between the two – a deseloper?Developer, although I design if I’m paid too via contract or real job.* Any other feedback?Give me an ASDoc like Flex has. If you did that, you could be sure I’d NEVER read the ActionScript help in Flash. I liked it was sorted in Flash 5 and some of MX with the Object > methods, Object > events, Object > properties style.Also, define the base classes more. You gals and gusy spent all this time creating this awesome framework, and only documented the controls; UIObject, UIComponent, DepthManager, UIEventDispatcher, StyleManager… those dudes.

  3. Julian says:

    I would really like to see a easier way to customize the help. The only books I use are the component and actionscript dictionary and some custom help books. I would love to turn the rest of the stuff off. I know I could just delete the files and folders but seems like there should be a better way. Also an easier way to order the books would be great.

  4. JesterXL says:

    You know, now that I think about it, with the advent of LiveDocs, what’s the point of Flash Help anyway? Unless it showed the comments LiveDocs has, I really don’t see a point of keeping it around.

  5. N Rohler says:

    I think that the built in docs are helpful, but how about the option of downloading & displaying the comments without opening a separate browser window?* What book(s) do you use the most?AS Ref & Components dictionary* Where would you personally like to see the “most improvement” or attention? (Maybe you don’t read a book now becuase it’s poor – but you would read it if it was good/improved).I agree with JesterXL. I’d really like to understand more about the background framework. It clearly is very powerful, but it’s hard to just jump in when there isn’t much documentation.* How do you use the books? (Ie: do you look for tutorials, code snippets, high-level workflow stuff, etc?)Reminding myself of method/prop names* What are you: a developer, a designer, or a hybrid between the two – a deseloper?Developer* Any other feedback?Thanks for listening to my feedback 🙂

  6. Josh Buhler says:

    A good reason for keeping the Flash Help around is those times when you’re not online to use the LiveDocs. But the ability to search the LiveDocs from the help Panel would be cool.

  7. Jensa says:

    I use the dictionary only. If it worked, I’d use the docs for the components too, but about 50% of my help files are blank for some reason? For all of these I have to use LiveDocs instead.Since you’re working on this – please look closely at how PHP.net has organized/implemented their documentation. It’s heavily moderated, but there’s gold in almost every comment. There are just so many things that are not good with the current LiveDocs. Read Jeremy Allaires blog from a year or two back and you’ll find more info there, since he also asked this question.J

  8. Kevin Hoyt says:

    * What book(s) do you use the most?Easily, the ActionScript Language Reference gets the most use from me when developing in both Flash and Flex. After that I find that I use the Components Dictionary a good deal. It’s more valuable for Flash, but handy with Flex on occassion as well. Finally, not part of the Flash docs per se, but I use the Flex MXML API as much as the Components Dictionary if not more.* Where would you personally like to see the “most improvement” or attention?I’m relatively pleased with the docs of late – they’ve made some really good advancements over the past couple of years. Personally I’d like to see JavaDoc-esque documentation for the AS Language Reference and Components (since there seems to be a slight separation between the Flash and Flex controls).* How do you use the books?References for styles, method properties, inheritance, and so on.* What are you: a developer, a designer, or a hybrid between the two – a deseloper?I’d classify myself as a deseloper, but most others would likely tell you that I’m a developer through and through.* Any other feedback?LiveDocs rock across the board! There will be times when I’m cutting and pasting straight from the docs and my application just isn’t working. Then I turn to LiveDocs and see that the problem has been commented on by another and responded to by MM.

  9. I have to agree about keeping the Flash docs around. Documentation within a tool is very useful. And since I help create a product that uses that documentation browser I would really like to see it kept around ;)However, I must say that there were quite a few issues to get around to create useful documentation that is easily navigable within MX04. I do agree with Jesse about the Object > Methods, etc., comment. One of the reasons this is isn’t done is because of a strange limitation in the MX04 doc build process: you can only have 3 levels, so 2 folders and the doc. This makes organization rather tricky. Depending on the complexity of the topic(s) it might not be feasible to have some documentation within the Flash Help Panel.Also, updates to documentation are not as straight-forward as it was in MX. In MX you can overwrite the XML files, add new ones, or remove the files and MX will discover them. In MX04 you have to create a TOC. This is nice for organization, so we’re not limited to alphabetical listings, but is an issue when an update is required. I built an updater tool for our product that pulls down new docs, etc., and throws them in the help directory (it could also delete, rename files, etc.). Then it must run through the directory and overwrite the TOC with the new list of files. The alternative of downloading all files, including the TOC, is not an option.Btw, for those that prefer the LiveDocs, you can have the best of both worlds – LiveDocs within the Flash Help panel. Remember, the Help panel is merely a slimmed-down browser, so you can visit external sites directly in the panel. Setup one item in the main list that contains an HTML page pointing to the LiveDocs and click that when you want to view it.Ok, now to the survey:* What book(s) do you use the most?ActionScript Language Reference and Using Components.* Where would you personally like to see the “most improvement” or attention? (Maybe you don’t read a book now becuase it’s poor – but you would read it if it was good/improved).I’ll agree with Jesse and N Rohler: more info on the framework would enable more people to understand what’s going on and how to create our own components to make the most of the MM framework.* How do you use the books? (Ie: do you look for tutorials, code snippets, high-level workflow stuff, etc?)Sometimes it’s just a reference look-up, and sometimes I want to know the high-level stuff, especially in planning.* What are you: a developer, a designer, or a hybrid between the two – a deseloper?Developer.* Any other feedback?I guess I gave that above. I would like to say that although there is room for improvement the MX04 documentation is now useful beyond MX’s reference docs. There will always be a need for reference docs, but the effort to give more is appreciated – I don’t think that’s said enough. Most of the time when I would complain about MX04 docs, I was really complaining about the components themselves. There are (still) descrepencies with functionality and docs in some components but I’d rather have some of the components changed rather than fix docs for them.I find what seems to be lacking when I look up a command is that little bit of extra knowledge about a parameter or such. Little things that really make a difference when you need to get a project finished. For instance, I was looking into the start method of the Sound object to see what the valid values of the second parameter are. There is a brief description of the parameter and no more. The parameter defines the number of loops a sound will play. I wanted a sound to loop forever, but there is no mention of this. The example doesn’t even use the second parameter. I realize it’s not feasible to have an example in the reference docs for every possible use of every command, but enough examples should be there to use all parameters of a command.Thank you for the opportunity to comment on this.

  10. Adam says:

    I don’t bother with the books, and simply stick with LiveDocs, since they provide user examples that aren’t in the other…..in LiveDocs, I primarily use the Component Dictionary to look up methods, and to a lesser extent the AS Reference. I usually end up copying code snippets. To make it more useful, a quick and dirty, simplistic example for cut and paste on each entry chould be accompanied a longer code example where a deeper understanding is needed. I concur wit the need for better docs on skinning. Better docs on printing would be nice too. Also, there’s quite a few basic classes never described anywhere, like mx.core.View, even though a bunch of components need one of those in the constructor :)The comments in LiveDocs are useful, but the overall *interface* to LiveDocs is *terrible*. The left and right pane doesn’t always work correctly if you link in, you’re constantly waiting for something to load, and the fact the left pane with your search or tree view can’t holod state is annoying. I would have thought that MACR could do a better job at this, perhaps as a sample RIA!I hope this doesn’t just sound like complaints. The documentation has gotten much better over the last few cycles, and I’m always impressed with how quick a Macromedian has followed up by email when I post a comment on LiveDocs.

  11. maura g says:

    The book/topic that I search for depends on the particular item I’m working on.I think any and all info on the SLIDESHOW FEATURE needs better explanation (about how to build a slideshow, and also about the limitations of this feature). Unfortunately, I wasted hours last spring (04) creating my first slideshow, and my final product was not worth the time that I spent creating it. Better docs would have saved me some time on that task by letting me know the limitations of that feature (!).I would prefer to be able to use Flash [over PPT] for online presentations — **however,** it was frustrating that my final Flash slideshow product was viewable only in FP7… I had to have the people who watched my demo download FP7, and found a marked difference in levels of enthusiasm about being asked to upgrade the Player. (Also, two people were working on machines that they were not allowed to download to… so they had to view from home.)The result meant going back to PPT which “everyone” can see easily. (Flash Paper would have been an okay solution, but I needed to be able to create timed slides, which FP can’t produce — but FP was able to deliver the *content* at about 1/4 the size of PPT files, so it’s quite useful).=========If I had a magic wand, I’d ask for a streamlined “edu only” version of Flash so that instructors and teachers could create informative animations for their students. But I can’t see many of them learning ActionScript…8^pFlash’s advantages over other technologies really kick in when it comes to illustrating/animating PROCESSES and also helping people think about PROCEDURES. Nevertheless, it’s my observation that the “full Flash product” is simply too complex for most instructors to learn — why move to Flash for their courste (or classroom) websites if they already use PPT…?As it is, a lot of instructional work has transitioned from “death by overheads” to “death by PowerPoint”… but at least PPT has a good wizard to walk you through intros and summaries — a feature that MM might want to consider for the slideshow feature…?Slideshows created in Flash, with animations, have far more potential to help people grasp concepts… so I think its a shame that the existing Flash software looks “too complicated” for the specific uses that many edu folks could make of it — animations, simple Quiz features, and slideshows.Personally, I think that a streamlined version of Flash designed **primarily for simple animations within slideshows** and aimed at an education and/or healthcare market would be a great idea.However, unless the Slideshow docs are hugely improved, I don’t see this happening… and although I really like ActionScript, I doubt that many edu folks would need more than simple drag-and-drop, or mouseOver features.I wish that MM would consider a simplified “streamlined Slideshow” version of Flash with a few basic AS commands built in as toolbar icons. (At the risk of being heretical, II would love to pull a “Drag&Drop icon from a toolbar onto my timeline; ditto for some of the other more common actions, including “Quiz” components.) Then aim such a product at teachers, instructional designers, sales employees, and presenters who want to help people grasp CONCEPTS, but arent’ likely to have time/energy for mastering all of AS.Please enhance the slideshow docs, and focus on:- limitations of slideshows (ie, FP7 is the minimal viewer)- include some sort of checklist or wizard to help users- better explain the options for a slideshow- better explain how to get an animation on a Level1 page- better explain what limits people may need on images…- better explain how to help users move through slidesAlso, any info on integrating Flash with RoboHelp woud be spiffy.Thanks for a chance to whine 😉

  12. Andreas Weber says:

    “The comments in LiveDocs are useful, but the overall *interface* to LiveDocs is *terrible*.”I couldn’t agree more with Adam here – frankly I don’t understand how MM can stand the idea of having it publicly accessible in its current, *excruciatingly slow*, bordering on the utterly useless, state.I’m happy with the quality of the contents of the docs – they improved massively over time. Keep up the good work!

  13. Prasad Talpade says:

    I use the Using Components book teh most some times ActionScript.I would like examples added which give us an idea of what the final output should/will look. I would also like better searching facility.I am looking at FlashMX04 as I am intrested in creating ‘Rich Internet Applications’ so there should be a seperate section which gives us basic knoledge about integration of Flash with JSP/PHP/ASP.

  14. jdehaan says:

    Hi everyone,I want to thank everyone for your throughtful responses about how you use the docs. It is incredibly helpful for everyone on the Flash documentation team to know what you use the most, and how. And also how you feel about the Help and LiveDocs systems! I have sent the URL of this thread to those involved with the Flash docs, as well as a synopsis of your comments. Of course, I’ll also keep all of this in mind for the sections I work on too.Thanks again for sending your comments!Jen.