Some of you may have noticed that we have implemented a new documentation format in the latest release of the Flash Remoting components. We are referring to this format as the “new ASDoc format”.
This is a new format similar to the format used in the documentation for Macromedia Flex, which was modeled after the JavaDoc format.
This should have very little, if any, effect on users. We just wanted to be clear that we are not releasing a new functionality or capability in the authoring tool. We are looking into further supporting this new documentation format in the authoring tool for future releases but we are planning nothing new in the short-term.
Mike, Is this something that is going to be common to all future Macromedia products? Would really love to see this make its way across into the CFMX documentation team. Ideally you guys could standardise on a doc format so that we can all leverage nifty tools like Mesh’s Resource Manager and other innovations.
That’s a good question that I’m not sure we can answer yet. Ideally we will move towards a single document format that makes sense for all products, but changing the full documentation to a new format is a very time-intensive and expensive project.
I think the docs in Flex are the best that we’ve ever done – and they use this new format – so there’s a good chance that all of the product teams will make an effort to move in that direction in the future.
Dan,
I’m in charge of the documentation team that put together this version of the Remoting documentation, and when I say team, I mean that it was not just a tech writer who contributed to this release. It was engineers, QA and tech support reps that all read and contributed to the docs. I want you to know that we do not take the docs lightly. We do not ignore our customers when they say that something is wrong with the way we do documentation at Macromedia.
The implementation of ASDocs is a direct result of Remoting customers asking us to implement this form of documentation. The process was not automatic, nor was it an effort to reduce the writing staff or to cut corners in any way. In fact, doing ASDoc was a significant investment in both time and engineering resources. Engineers and writers worked togehter to craft examples and insert comments in code. QA engineers worked to review each example. The only thing automated about this implementation is the generation of the HTML output. Nor, was ASDoc the main goal of this release. In fact, we spent a great deal of time in adding examples and re-writing API information.
We really did test each and every example in the doc. A very large effort was put into making sure that there were more comprehensive and extensive examples throughout. Apparently we missed the mark. I’m passing your concerns onto the engineering team. I’ll ask them to respond to you as well.
We do not want you to think that we are not trying to make these docs better. The concerns of our developers have been heard loud and clear. Everyone at Macromedia is focused on improving your experience with every document we publish. Everything from writing, to developing examples, to reviews has been scrutinized and every effort is being made to improve each and every process. Our efforts are not just on Remoting but also on Flash. Right now, we’re working a major project for Flash MX 2004 centered mainly on addressing as many customer concerns with the docs as possible.
That’s a lot of pages and a lot of work ahead of us. We may not fix it this time around, but we are trying to fix it. Keep sending in your bugs and concerns we’ll be listening and working to fix them.
We know your experience with our documentation has not been ideal. We’re doing everything in our power to change that.
Danny
I read your posting with a bit of surprise. Im really glad you are in there checking out the new components and documentation and keeping us honest. But I am surprised you came away feeling a lack of documentation. For this project, we dramatically ramped up our time commitment to documentation. As Erick mentioned, we had the whole team working on the documentation and also hired a skilled Remoting developer to write working examples for us. I can honestly say that documentation was a prime requirement for this release.
A few observations on the result of that commitment:
- We provided two full references, one for how to use Remoting in general and one for the detailed API reference. Both completely updated and with many more examples than before. Are you seeing both references? They are both in the Flash product and will be in LiveDocs form online this week so you can add your own comments, code examples, etc.
- We added 67 new examples in the documentation. We estimate that 96% of the Remoting API has examples. Every example was tested to compile and all but a handful that you point out here will run. Most that won’t run require lots of set up to work, so we did the best we could in providing everything to illustrate the use of the API.
- Two full example applications, one in the product and one on the Developer Center. We have more planned in the next month on the Developer Center. These are fully documented, running example applications with source code.
- Agreed, we could have added a few more links and well keep working on that in the future. But we believe we caught the most important links required.
- We rigorously tested every example at every major milestone in the schedule, including the released version before we posted it to the web. I dont believe you indicated that any examples dont work, correct?
Response from others in the community has been very strong, and documentation is no exception. Have you seen Steven Websters comments (http://www.richinternetapps.com/archives/000057.html) or Tom Mucks comments (http://www.flash-remoting.com/notablog/home.cfm?newsid=83).
After reading these comments and giving it some more time, let us know if you still feel the documentation is lacking.
Lucian Beebe
Remoting product manager
Are there plans to have a PDF available for download on the Macromedia website of the new Update? It does not appear that I can print the new/entire “Using Remoting” or “Remoting Dictionary” from within the help panel unless I do it an entry at a time.
Additionally, I am having problems with some of the documentation being “fetched” correctly when I navigate through the book/tree structure on a Mac OS 10.3 system. Errors are returned. These problems are not present on my win XP system. Any thoughts on how to fix or who I should notify specifics to?
Tom
Where is the CustomerInfoExampleAPI example program?
The Service object help file is missing some vital information. Mainly, it does not state or give examples of how parameters may be passed to the remote methods. This seems to be a fairly major oversite.
Also, mentioning the CustomerInfoExampleAPI example application without informing the reader on where this application may be found is rather silly.
Where can I find an ASDoc reference document and a tool to convert (to HTML)? Surely Macromedia must have released these by now?
document and a tool to convert (to HTML
what is the main idea of creation the new documentation format for Macromedia Flex?
seems it will be useful
There are a lot of formats. Why they dont use them and discovered new?
Any one who relies on the documentation will tell you that many of the code examples are “cut n paste” from one place to the next. There are thousands of examples that simply “trace output” or “loop” a method. Worse yet, many of the examples are simply incorrect and clearly untested. When an attempt to include a more complex example, many times key portions are omitted.
All free videos here – http://freevideo.blog.ijijiji.com/
Cool site! Placed to bookmark!
think the docs in Flex are the best that we’ve ever done – and they use this new format – so there’s a good chance that all of the product teams will make an effort to move in that direction in the future.
why don’t you try another substitute such as; this http://www.neglog.com if not, why all information cannot be retrieved from all websites.
This one makes sence “One’s first step in wisdom is to kuesstion everything – and one’s last is to come to terms with everything.”
Hello! Good Site! Thanks you! mbkzvrmneqph
sdf
Hi webmaster!
Hi webmaster!
Hi webmaster!
Hi webmaster!
Hi webmaster!
Hi webmaster!
Hi webmaster!
Hi webmaster!
kilometro londres bristol
lease equipment
ivss ve
receta cocina mexicana
school graduated
alquiler de coche en aeropuerto lanzarote
discovery kids
foto lolitas
roxana diaz jorge
distance education
hawai i isla grande
movie rental online
event barcelona
foto rbd manga
quick cash loan
hawaii real estate
nacimiento sting
norte castilla
lycos jardineria
tipo de main board