Examples, examples, and more examples

When we ask ActionScript developers what they want from the Flash Platform documentation team, their consistent answer is: more examples. There is no such thing as enough when it comes to code examples that developers can use to learn the language, solve specific problems, and share ideas with others who are working on similar applications.

The secret: our existing ActionScript 3 documentation actually HAS a decent range of examples. The problem is that these examples are somewhat well hidden. To solve this problem, we’ve analyzed pathing info (provided by Adobe’s Omniture acquisition) that tells us what users are searching for, where they are looking, and how we can help them find what they need.

The ActionScript 3 Developer’s Guide‘s appendix (How to use ActionScript examples) explains how to work with different types of  examples. Until recently, this appendix did not make it easy to find the ZIP file that contains the example source, never mind explanations of the functionality that each example demonstrates. Here is a link to the examples ZIP, followed by a list of examples and their explanations. Let us know what you’d like to see added to the list.

Example ZIP file: Flash Professional CS5 and Flex 4 samples

List of examples:

2 Responses to Examples, examples, and more examples

  1. David Buhler says:

    When I am looking through documentation, I want to verify the code does what I need it to do. The code has to solve the same problem I am trying to solve. The approach above fails to solve a few common problems:
    1) I am unable to verify the code solves the same problem I have. I want to see a working SWF.
    2) I want the SWF to show me the problem (a before state) and a solution (the after state).
    3) I have to download a zip file. This means I have to download the zip file to a specific location. I have to remember the location. I have to extract the contents of the zip. I have to filter through unrelated files to find the one I need. I have to work through a very large class, with highly unrelated code to find the possible solution (again, I don’t know if the solution is the right solution, because I couldn’t test it).

    If I have to spend more than 2 minutes looking for an answer to a problem, I pursue another avenue. Over the course of an average day, I need answers to 20 different problems. The approach above would take me 30 minutes, just to figure out whether the example did or did not meet my needs. Multiply 30 x 20, and you can understand the problem with the approach.

    The best thing Adobe had going was Peter de Haan’s flexexamples website. The examples were short, succinct, and provided before and after examples. Related examples existed on other pages, instead of having to dig through a long list of similar examples on the same page (as is the case with livedocs). Others could chime in with potential improvements, so developers could assume the lowest posts might offer a more elegant solution to a problem. Alas, Peter’s site is so terribly slow now, developers pursue answers elsewhere, and are forced to visit sources from a random assortment of people, whom they neither know or trust.

    The FlexExamples Air App doesn’t help me, either. The real world workflow is people search on a type of problem.

    They enter search terms:
    “how to add components to other components at run-time”
    “checkbox do not show after page refresh” [sic]
    “itemrenderer changes when scrolled”
    “itemrenderer changes icons when user scrolls with scrollbar”
    “speed difference between Vector + Array + ArrayCollection + ArrayList”

    Try finding answers to those problems within the FlexExamples Air Application. Worse, try finding answers to those questions within the LiveDocs.

    The Adobe CookBook doesn’t offer any help, because it fails to show working examples. Worse, there is no code formatter or beautifier. Instead, the cookbook looks like raw Notepad examples of code.

    So here’s my best advice:

    Create a Search Engine Friendly website with WordPress (you can find free SEO templates for WordPress). Or dog-food it and use use MURA.

    Write a little widget to create Flash Applications on the fly. Some websites create Flash Applications through a web-based IDE. Such an approach would be an innovative solution to showing real examples.

    Keep the examples short. Provide a link to the livedocs website, but remove the Flex Apps from the livedocs.

    Simplify: Keep LiveDocs pure (remove the SWFs). Kill all the AIR applications for finding Flex Help. Between the AIR Community Help, TourDeFlex, TourDeLiveCycle, Flex.org, LiveDocs, BluePrint, CookBook, I can’t even remember which one does what, or which one works on my OS at home or work.

    It’s okay to experiment with Help apps (for awhile). Look at Google; They throw things against the wall all the time. When the apps don’t stick, they shelve the project.

    Adobe should look at the 10,000 top search terms (Yes, I’m aiming for a lofty goal) for Flex/Air/Flash related problems. Title each page with one of these search-terms. Need Help? Talk to an SEO expert. Find the best SEO tool that shows these common search terms. Adobe could write 500 posts with examples, related to questions about validation routines, alone.

    Make it clean. Make it fast. Each time I see the giant header and footer and the small font, I just back-browse and keep searching. When I hit the Adobe HelpDocs, I have increase the font size, wait for the navigation and header to load, and those extra 10 seconds drive me to look somewhere else.

    Get real. Look at the “AlarmClock” example you have. When was the last time someone said, “I really need to build an Alarm Clock in Flash?” I know what you’re going to say. “This is meant to show how to do X in the UIComponent Lifecycle.” If that’s the case, why can’t the example be called “Examples of the UIComponent LifeCycle”? Why can’t the project name describe the intent?

    • Karen Leeburg says:

      Hi David,
      Thanks for providing such a well-thought-out critique of our current ways of providing examples to our developer audience. Your constructive criticism and ideas about how to improve are very much appreciated, especially given that you’re clearly a very experienced and long-term user of Adobe’s developer products and docs. Your input is already receiving wide circulation within our organization, and will bolster our efforts to give developers what they need.