Reviewer Notes: What we look for in Code Commenting and Help Documentation

“Short term loss, long term gain.”

That’s my greatest advice to you if you are planning on writing any kind of documentation.  It may be boring, and it may be time consuming, but the small investment of time it takes to write good documentation far outweighs the potential time it would take to continually answer and write to all your users with the same answers over, and over, and over again.

If you have been authoring files on Flashden for a while now, you will already know that there are two mandatory requirements for documenting your uploads.

If you are a new author, here’s a quick summary:

• You must always comment your ActionScript
• You must always provide a well-written help file

If your ActionScript code is not properly commented, your file will be rejected.  Similarly, if your help documentation is not adequate, your file will also get rejected.  So what do reviewers look for in your documentation when they review your file?

Code Commenting

Flashden requires code to be commented for one basic reason:  So it can be understood by the customer and be quickly modified or customized, if necessary. However, it is always good practice to write readable code for your own benefit too.  The code you write and comment today will most likely be used for a different project tomorrow, next month, or even next year.  So by having well-structured and documented code, it will make it easier and quicker for you to go back to your own code at a later date and re-use something you have already written.

When commenting your own code, try to put yourself in the shoes of another person reading your code for the first time.  Here are some general questions and guidelines you should always remind yourself about when writing and commenting your code:

• Is your code readable?
• Do the classes and functions have easy-to-understand names?
• Is it clear which variables are the most important variables?
• Are the most important variables in the same location in your ActionScript, so that the user can make basic modifications very quickly?
• Whenever you create a new class or a new function definition, you should add a comment explaining what the class or function does.
• If you have a long block of conditional statements, consider commenting what should happen when each conditional is executed. In doing so, you can concentrate on the implementation of one aspect at a time without having to remember details of the entire functionality or application you’re coding.

Quality, not Quantity

One important thing to make clear here is that there is a difference between good code commenting and bloated code commenting.  Flashden, nor any good developer for that matter, is not suggesting that more is best.  Good, effective code commenting is not about quantity of comments.  It’s about quality.  Be direct and not too verbose with your comments, but comment important, critical classes, variables and conditional statements, with a goal of educating your customer on how to manipulate and execute your code/file.

Good commenting is often overlooked, but it is an essential programming skill to acquire. Learning how to comment code efficiently is a good habit to learn that will serve you well in the future should coding become something you pursue as a career.

Help File Documentation

It does not matter if your new Flashden file is a preloader, a set of animated icons, a rotating XML image banner, or a fully-blown site template — providing a help file for your work is mandatory.

Of course, if your file is very basic, such as a percentage-based preloader, or a timeline animated graphic, there’s no need to write pages and pages of documentation — quantity of documentation is not necessarily the goal here — but what is important, is that your customer can read your help file and know immediately what they need to do to either deploy your file and/or modify or customize it.

File formats

Help files can be in any of the following formats as long as it’s written/typed, and is printable.

• TXT
• DOC
• PDF
• HTML

The above file formats work across all PC/Mac/Linux operating systems, so avoid using any specialized or proprietary formats when saving your documentation.

Simple Files

If your file is very simple by nature, such as a preloader, an animated icon set, or something so simple that it can be dragged and dropped from one FLA document to another, then just say so in your help file!  Make sure you are providing the user with everything they need to know to use (and if necessary, modify) your file, and keep it simple!  But always include a help file, no matter how simple your file is.

Hints and Tips

• Assume nothing!  Never write a help file thinking that your customer knows everything you do.  If your file requires a user to add an ActionScript linkage ID to a library asset, explain the full process how to do this. Don’t just write “Add a linkage ID to your movieclip.”  Be very literal and procedural.  Explain every step of the process to ensure that the user will be able to fully understand the necessary steps to update and maintain your file.
• Number items/steps sequentially.  This is a great way to support your file because, if a customer or two starts asking questions about how to do something with your file either by e-mail or in a file thread on Flashden.net, it’s going to save you a ton of time by simply telling them “See question/answer 5 in my help documentation!” instead of repeatedly typing and responding to the same questions over and over.
• Consider adding a “Frequently Asked Questions” section to your help file.  When your file gets approved and you notice that more than one person keeps asking you similar questions, you can go back and edit/update your help documentation using the FAQ section of your help file so that all your customers always have access to the latest help document.  It will save you a lot of time in the long run and not have to keep responding to the same questions time and time again.

DOs and DONT’s

• Help documentation must always be in well-written, understandable English.  Documentation (and even code-commenting) in another language is not acceptable.  Poorly written grammar is not acceptable either.
• If you are using any permitted third party plugin or tween package always give credit and/or a link back to the Web page where it can be downloaded if this is stipulated in the product’s terms and conditions.
• Do not post help in your file description.  This prevents unintentionally supporting your file to anyone who has not purchased your file.  This helps fight against file and piracy theft.  If you want to do everything you can to protect any profits you make, do not give detailed help/support information away in your file description.  Features, of course, tell the world about, but information about how to update and maintain your file should be reserved for customers who purchase your file only.
• Do not create a help file that simply says, “Click this link to view online documentation.”  This is not acceptable and your file will be rejected.  There are numerous reasons why you should not host your help file externally. Firstly, as previously mentioned, this may help people use your file that may not have actually purchased it.  Secondly, there are occasions where users do not have Web access or are working locally and would therefore need to use the provided text file with your download.  Simultaneously, your personal site may become unavailable over time, so as you can see, providing a text document with your main upload file is very important and this is why it is mandatory.

Videos

Videos are a great way to show users how to use and update your file, and we love to see how authors are using video to assist customers with their files.  But please note: You are not allowed to just provide a video to assist users.  Your first priority is to always provide a written/printable document.  Why? Because it is quicker for a customer to scan and read text than have to sit through a 5, 10, or 15 minute video.  It is a proven fact that it is quicker to find pertinent information in a text document in a matter of seconds compared to sitting through a video. Videos are terrific for more involved processes or more complicated tutorials.

Conclusion

The combination of commented code and well written help documentation is a win-win situation for both author and customer.  It helps the author long-term by saving time.  It is better for authors to establish and maintain good documentation rather than have to keep answering the same questions over and over in e-mails and file threads.  If customers find your help documentation easy to use and understand, they are going to enjoy using your file, may feel more inclined to rate your file, and may come back and purchase your files again because they know you support your files well.

As well as giving you some insight into what reviewers look for when we review your code and help documentation, I hope there are some other tips here that stress the importance of how quality documentation can actually save you time and perhaps increase your sales too through reputation.