Flash File Documentation is Now Mandatory

There’s nothing worse than opening a Flash file and not knowing how to customize it or edit it. Where’s the ActionScript located? How do I edit the XML file? This is why Flashden introduced “Quality of Documentation” to all Flash files about a year ago. By allowing our authors to provide documentation and then allowing our reviewers to carefully rate the documentation, the result has been not only increased customer satisfaction, but a better way for authors to offer support to customers which has indirectly lead to an increase in file sales.

Having kept a close eye on Flash documentation for over 12 months and having investigated ways to improve our documentation structure and process, Flashden is pleased to announce a new and very important requirement: Documentation is now compulsory for ALL Flash files.

What does this mean?

Quite simply, if there is no documentation provided when you upload a Flash file, your Flash file will be rejected.

What kind of documentation do I need to provide, and how much?!

Most authors won’t have anything to worry about. Most of our users typically provide adequate documentation for their files. But in an effort to improve the overall quality of files and quality of documentation on Flashden, providing documentation is now mandatory rather than optional. The criteria for documentation is as follows:

• If your file contains ActionScript, it needs to be well commented. This is a requirement! If you create an image gallery or a Web site template that is heavily ActionScripted for example, you will need to ensure your code is well commented. By “well commented”, this means that any important variables or functions that can be changed and customized by the user within the ActionScript needs to have corresponding comments to assist the user. Anything that you think will assist the user to understand and interpret your code, you will be better off commenting it than leaving it uncommented.
• If your file is quite basic, let’s use a preloader file as an example, then you will still need to provide some basic instructions within documentation. “Drag the preloaderMC movieclip from the FLA into your own project.” is acceptable, should this be what a user needs to do in order to re-use your file. Please do not make any assumptions that the user already knows what to do: If you provide basic instructions to a user for a basic file, this is better than no instructions at all.

What documentation is NOT

There are still a lot of authors that only provide information about what their files does in their documentation. But a description of solely what a file does does not constitute a help document. For example, a help.pdf containing “This file is an image gallery and is really easy to update.” will not be acceptable as adequate documentation. Instead, authors now have to take responsibility to ensure that users are provided with clear instructions how to use and customize the files they sell on Flashden. This can easily be done through a help file.

What format does my help file need to be in?

We don’t mind! It could be an HTML document, or maybe a .txt, .pdf or a Microsoft Word .doc — even a video file if you prefer, just like some authors are already doing for the benefit of their customers. As long as you provide some type of adequate documentation for your potential customer(s) within your download file, you are fulfilling the requirement.

Please also note: Although providing help in Flash file descriptions on your item page is an excellent service to offer, your first priority should be to provide written documentation (.txt, .html, .pdf, .doc etc…) as a separate file in your main file upload(s). This is to ensure that any user purchasing and downloading your file will be able to find documentation in their download.

Could you give me some general tips how to write good documentation?

Sure, we’d be glad to!

1. Imagine the person reading your documentation has never opened your file before. How are you going to tell them how to update and customize your file?
2. Think about the main features of your file. Have you fully explained how a user can use and manage these features?
3. Try writing your documentation as though your parent or another family member had to use and update your file. Make it really simple and to the point.
4. Provide instructions as a bulleted list or a numbered list. Decide how you will break down your instructions into smaller, easier steps so that someone can follow your instructions.
5. Be sure to state specific information that might help users. For example, if all image thumbnails in your XML News module have to be the same dimensions, or they need to be located in a directory with a particular name, be sure to state it in your documentation!

Do I need to add documentation to files I already sell on Flashden?

No. There is no need to go back and add documentation to any existing files on Flashden. The new rule of providing documentation applies to new uploads only, beginning on 26/05/2008.

What about files already in the queue?

We are allowing a grace period of 4 days before the new rule takes affect. This will allow sufficient time for files already in the queue (that may not have documentation) the opportunity of being approved. Once the grace period ends on 26/05/2008, the new documentation rule will be in force.

As always, we value your feedback and invite you to contact us at support or leave feedback to this blog post if you have any questions or concerns.