PHP Like Documentation for ActionScript

Yesterday I asked about public bugbases, and got a pretty good response. However, half of the response ended up asking about PHP like documentation for ActionScript. The PHP docs essentially allow users to add comments and examples at the bottom of the documentation.

So, here is the question for today:

Would you be interested in a PHP like documentation system for ActionScript? What features would you like for it to have?

Btw, we have a similar system already setup for most of our servers and languages, including CFMX, Flash Remoting and JRun.

Post your thoughts, comments, suggestions in the comments section.

42 Responses to PHP Like Documentation for ActionScript

  1. khan says:

    It will be very usefull.the idea with comments and examples are great.My suggestions:- prototype section.- explanations for undocumented functions- Multiple languages

  2. Peter Elst says:

    It sounds like a really good idea if managed correctly, if not it is bound to end up in one big clutter of support questions and badly written code.Just my two cents 🙂

  3. Peter Hall says:

    Yeah, I have to agree with Peter. Also, these user comments need to be fully searchable or else their usefullness is really limited.(as a sidenote – mm support could do with some all-round searching improvements)

  4. zeh says:

    > “Would you be interested in a PHP like documentation system for ActionScript? What features would you like for it to have?”Most definetely. Ever since I started using Flash MX heavily I have longed to have something like PHP.net for it. It’s just too useful: you look for a given command (say, the Date object) and you find tons of examples below. There are way too many useful users code on php.net (on Flash MX’s case that’d work as prototypes and the such).

  5. Waldo Smeets says:

    What I would like to see is a specific function in the actions panel that allows us to directly lookup the page beloning to the actionscript that is selected.So instead of opening the Reference Panel this links to the online page with the comments from the users.

  6. steve w says:

    What? you don’t have it up and running already? ;-)I’d like to see a section for OOP and best practices for implementation.Thanks for considering the project. I think it would have widespread support due to the fact that MM is authoring it.

  7. Mike K says:

    It would be really handy if in the next version of the authoring environment, the reference panel could be updated/sync’d on demand to include the documentation and comments from the site. The database could be pushed to XML and the reference panel could use that. Of course it would be pretty hard on bandwidth I suppose. Just a thought.

  8. Sean says:

    Absolutely – PHP.net has the most useful set of documentation around. A similar database for actionscript would be awesome.

  9. Todd says:

    My only complaints about livedocs is that it’s sloooooooow. 😛

  10. Todd says:

    Well, it’s usually slow for me… today it’s making a liar out of me. ;P

  11. llama says:

    yes! i like php and flash and this is really good idea. Actionscript doc is still little incomplete!but it would be great to have also offline version in .chm, like php has. it’s faster, with great fulltext search.(I still don’t know, why flash mx has help in html (like flash 5) and dreamweaver/fireworks has help in chm. chm is definitely better! stupid search in java sucks)

  12. Yes PUHLEESE! :-)This would be so very useful.

  13. Definetly a great idea. On-line commented manuals, like the ones for PHP and MySQL, are an invaluable resource for self-taught developers. Extending this idea to ActionScript would make things easier for lots of people learning the language.For that to work, Macromedia needs a team of editors to review the posts and make some QA tasks.Also, it would be very important to have it available in several languages, since some examples could be language-sensitive (e.g. a way to display names of months and days in Spanish, etc.)

  14. Yes, please make sure it is edited / QA’ed – bad advice is worse than no advice.Otherwise – please do it!

  15. Justin says:

    I would be in support of it.Since Flash Remoting’s debut, I thought the LiveDocs on MACR’s site tried to immitate what PHP.net had done.I like the commenting system too.Two things I would do to MACR’s site.1. Add the PHP Documentaion style to the site2. Downsize the forums and integrate it with the new Documentaion style.I’d like to search and find posts in both the forum and cross links in the Documentation

  16. Mike Chambers picks up the stick on ActionScript documentation

    This is something I discussed with Jeremy Allaire and possibly also Mike Chambers two years ago – At FlashForward in NYC 2001. The PHP documentation…

  17. genaro says:

    Hi, Rolf Ruiz has some pretty good PHP-Flash stuff, check his home page at http://www.alesys.net

  18. genaro says:

    Hi, Rolf Ruiz has some pretty good PHP-Flash stuff, check his home page at http://www.alesys.net

  19. genaro says:

    sorry about the double post

  20. Daniel Dura says:

    One of the most useful features of the php.net documentation is that you can put your search terms in thier url. For example:If I have a question about date() function, all I do is type inhttp://www.php.net/dateAnd I am either shown the information for that function, or a search list of similar functions and objects.This would definitely make the actionscript/cfmx documentation better. It really isnt too hard to implement either.

  21. Daniel Dura says:

    Another comment, I think one of the main reasons that Macromedia’s live docs have not been successful is because of its implementation.When you are going through the documentation, I dont really need to comment on the page that the table of contents is on. It seems like the comments are to spread out. If I want to find information, do I go to the table of contents page to look for comments, or do I go to the page that discusses that topic?Php.net is has set up their documentation with full examples, in a very organized manner. There seems to be only one or two levels max. It is mainly a reference for properties, objects, and functions. The interface is simple and easy to navigate. It is geared to be a quickly accesible reference. Macromedia’s implementation is more like a book format with commenting available.

  22. bokel says:

    Great !If you are concerned about QA, you shouldmake it a wiki. The flash community will assure the best quality you’ll ever get.bokel

  23. Daniel Dura says:

    I dont know if it should be as much QA really. ONe of the things that makes the PHP.net version so great is that in general, most of the posts are ways of implementation of the function being discussed. You can learn great techniques, etc. Very few of the posts are actually questions regarding that function.

  24. bokel says:

    QA == Quality Assurance == expensive == it will never happen

  25. Daniel Dura says:

    AH….wow…..just had one of those Homer moments 🙂

  26. Ralf Siegel says:

    I think I might like having a 1-click (c) Babylon kind of thing for ActionScript.http://code.audiofarm.de/temp/BabylonJDKDoc.gifClicking on e.g the toString() method pulls in the latest documentation along with a little example, comments & hyperlinks and stuff. With that you are not necessarily tied to Flash’s IDE, but can use it anywhere, like when you are reading through Flashcoders e-mails or blogs.

  27. Justin says:

    Check out Marc Canter’s (http://topicexchange.com/t/thematrix/) Topic Exchange. Could this be an extension of the documentation integration style…Quick searchable facts on Actionscripting/ColdFusion/Lingo functions and techniques, user comments/examples, cross-referrencing documentation from forum posts to knowledge base – from knowledge base to user examples – from user examples to blogs

  28. a!e says:

    My €.02…I agree a Wiki would be a nice idea, specially usefull with cross-referencing. But I’ve come to love the PHP help system. Maybe they wouldn’t mind sharing the code for the system (I’ve been taking a quick peep, but I haven’t found an explicit link to the project, though they have a ‘show source’ link on each page)As for LiveDocs… it is a good idea, but the implementation is… crude… it looks like a patch on the page, actually. Not something I would like to use daily.And, please, try *not* to be like MSDN. It is a searching-nightmare (it is best searched through Google, go figure…)

  29. Robert Hyde says:

    Not only could there be PHP style user additions but also better syntax definitions, plus more code examples in the docs themselves.

  30. sheel says:

    oh yeah!! please make sure that SEARCH function in that documentation is the best otherwise it doesn’t help.

  31. Kraken says:

    Yes, please. I’d like something like that for Actionscript.

  32. Ryan Spohn says:

    Yes, it seems like a great idea if it had the ability to be managed (edited), and was fully searchable.

  33. Stephan says:

    Nobrainer?

  34. zekus says:

    great idea… I’ll wait for that!

  35. TomCollins says:

    Its a really good idea. So many Actonscript features are poorly documented, with a specific lack of useful examples. The current documentation is useless at demonstrating the range and application of AS features. If Macromedia can’t be bothered Im ure Flash users can. I also agree that some form of moderation is required.

  36. Julio Garcia says:

    I think it would be greate! I can not count the times where the php.net user comments and examples have pulled me out of some serious trouble.

  37. jensa says:

    I’ve discussed this with Macromedians many times, but they seem to praise LiveDocs vs. seeing what is so great about php.net? LiveDocs aren’t bad but they are:1. Not searchable2. Has very few comments3. Are poorly structured4. Few examples and hardly any tricks or workarounds for difficult issues5. Generally combersomePHP.net just excels at this, making it really easy to find what you’re looking for. I seldom browse more than 3 pages before I find exactly what I need. LiveDocs is a totally different story, so I wouldn’t even call it “similar”.Editing the comments will be a massive job, but it will surely be worth it both in the way of less support calls and increased and more usable documentation with lot’s of examples.

  38. slamdunkinpool says:

    Aye you forgot thee Gotchas eh section.Please add a ‘Gotchas’ section to LiveDucks.Samples, tutorials and templates are already accessible at Support site or in IDE, but it would be good if there are some downloadable Demo swf’s available which shows …wot flash can do..and ..how(code) it does that. Somethin similar to Demo(do try it) program from wxPython which shows the code and GUI widgets side by side.Oh good job with the LiveDoc design. Hope you have adding pics/graphics(switchable on/off), switchable style sheets for LiveDoc’s is in the pipeline.

  39. Daniel Spohn says:

    Are you talking about something like bugzilla?