Logged In

Flash MX 2004 Documentation: Responding to Customer Concerns

Our main goal in the documentation team is to make sure that every time you use the Macromedia Flash documentation, you find what you need and get answers to your questions. Though we try to anticipate every issue you may encounter when working with Flash, you may still find that the documentation does not help you every time. We're working to improve that experience with every release.

When we released Flash MX 2004 a year ago, you told us loudly and clearly that we missed the mark. In the newsgroups and lists, in online surveys and telephone interviews, you told us that the powerful new features of the product were inadequately documented. You also told us that the documentation had gotten so big that you were having a hard time finding information, and that you needed many more examples of real-world uses of ActionScript.

There was obviously a lot of work to do, so in a pretty historic move we decided to build another release of Flash; mainly to fix the problems with the documentation. We think we've made great strides and that the documentation is much better today than it was a year ago, thanks to your feedback. Here is what we did:

• Added over 400 new code examples
• Increased the percentage of entries in the ActionScript Language Reference with examples from 43% to 98%
• Increased the size of ActionScript documentation by 85%
• Added 21 new documentation sample FLA files demonstrating common application functionality
• Fixed over 2000 doc bugs (from sources like LiveDocs, beta lists, direct customer feedback, and reviews by the development team)
• Added two new chapters about working with components
• Rewrote two existing components chapters, including styles and skinning information
• Updated styles and skinning information for every component
• Added inherited APIs to component docs
• Documented component APIs and their inherited APIs all in one place
• Moved one of our Flash engineers to a permanent position on the documentation team

Talking to Users

For this release, we wanted to make major improvements to the documentation. To focus on the key issues, we enlisted 20 users who were willing to talk to us, in detail, about their problems with the documentation. Every writer on the team spent time on the phone with several of these users. To gather more information and verify our findings, we also sent surveys to Flash customers at large. From this research, we defined three goals for the release:

• Improve the quality and accuracy of the current documentation
• Enrich the content of the ActionScript and components documentation
• Make it easier to find information in the help system

Improving Documentation Quality and Accuracy

Our users had two major complaints about the Flash documentation: too many bugs and not enough examples. To improve the accuracy, we asked the engineering team to review thoroughly all the documentation several times during the project. We also asked users to read the documentation and report bugs. Comments from both the engineering team and users were made using the LiveDocs system, an online feedback tool developed during the release. This process identified about 2000 bugs, and we're happy to say that we fixed all of them.

When we looked at the examples in the reference guides, we found that while there were examples for some APIs, they were either incomplete or out of date. Many APIs did not have any at all. We decided that the best way to respond to developers' need for real-world examples was to have a real-world Flash developer create them. We hired Jen deHaan, a longtime developer, instructional writer, and active member of the Flash community, to help us add more useful and complete code examples.

With Jen's help, the documentation team added over 400 new code examples, raising the percentage of APIs with examples from 43% to 98%. For an idea of the new code example standard that we set, see the example in the MovieClipLoader.onLoadProgress entry in the ActionScript Language Reference.

Enhancing ActionScript and Components Documentation

In addition to the lack of examples, users told us that the information in the ActionScript Language Reference did an inadequate job of explaining how to use the APIs. It was also apparent that developers were having trouble creating new components and that there wasn't enough information on customizing components.

Changes to the ActionScript Language Reference

To help developers understand how to use APIs in their work, the documentation team added 21 new documentation sample FLA files that demonstrate common application functionality. See the new example in the LoadVars.Load() entry in the Action Script Language Reference. We also added a new best practices chapter that provides recommendations for creating Flash content. See the new Using Best Practices section in the Using ActionScript chapter in the Flash manual.

In addition, we added data type specifications to the Usage section for each entry (see the Usage section for any entry) and created a new appendix for deprecated entries.

Changes to the Using Components Manual

Because many of our users were having problems using components and integrating them into their applications, we added two new chapters:

• Creating an Application with Components
• Handling Component Events

We also heard that it was difficult to understand how to create and customize components, so we rewrote the Creating Components chapter, and added more information about skinning and styles to the Customizing Components chapters. We also updated the styles information for each component (see the Button component for an example). See the updated chapters:

• Creating Components
• Customizing Components

Making Help Easier to Use

Last year's release of Flash MX 2004 included a new updatable help system. The goal was to use the Update feature both to enhance the help system with new information and respond quickly to user requests and issues. However, even with the over 600 pages of content we added in updates throughout the year, users were still telling us they couldn't easily find the information they needed. In some cases, the information was there but hard to find because, with so many pages of content, it was difficult to know where to start.

Although we couldn't make sweeping changes to the help system in this release, we addressed some usability issues by providing two new features in the help system. We created an interface to guide new users through the documentation (see Figure 1). We also provided a ReadMe file that lists all the changes made to the help system with each update.

Figure 1. New Welcome interface to help guide users through the documentation

Many help topics were short overviews and didn't give users enough information, so we added lists of related topics to provide a path for users to follow through the content. See Working with Flash Documents for an example of a section with related topics.

What's Next

The job of improving the Flash documentation is not over. There's always something more we can do. The documentation team will always approach each new release with the same questions:

• How can we help users understand the product better?
• What are users asking for in the documentation?
• What can we do to give users the best possible experience with the documentation?

This update would not have been possible without user input. We continue to rely on LiveDocs for direct feedback. So if you have a comment, please add it to the LiveDocs system. With your feedback we'll make sure that every release of the documentation gets closer and closer to solving your problems every time.

About the author