Flex LiveDocs: Two Minor Annoyances
Generally speaking, when I am working in Flex I have LiveDocs open. There is, quite honestly, no way I can store the depth of information that the Flex SDK or LiveDocs contain. Life is much easier when you have a reference.
Today, I am looking at I18N, or Internationalization. There is a whole section of content in the LiveDocs located here. The content is concise and informative. But I have two easily remedied complaints about the system.
1) Navigation at Page Bottoms: The I18N section has several pages. Some pages are fairly short. The second page is very long. If you navigate to the bottom of the page and wish to continue to the next page (a natural inclination), you must scroll all the way back to the top of the page to find the next page button. Sure, you could use the left-side navigation, if it has opened up properly — often if you navigate to the page from a search engine link the left-side navigation does not open up to reveal the section you are viewing. I don't mind long pages, but if I am navigating between several pages trying to understand what the LiveDocs are trying to tell me, this navigational omission irks me to the point of opening each page in separate tabs.
2) View Source and Examples: Uh, hello? Sure, having the code in-line on the page is helpful, but ultimately when there are several files involved, being able to right-click and select "View Source" is mighty handy. In the I18N example, there is an example at the bottom of the second page (yes, the bottom... see annoyance #1) that basically shows me how to change languages at run-time. But since the example requires several files, it is a little difficult to see if I am setting it up correctly. If I could view the source for the example, which would include the resource files that are required, I would have fewer questions. People learn in different ways. Some people learn by reading the descriptive and instructive language in the LiveDocs pages. I tend to learn more by reading code.
Comments (5) | 
Print | 
Send |
del.icio.us
| 
Digg It!
| 
Linking Blogs1889 Views
Comments
The second one is harder. To get View Source functionality (that is, the nice frameset
that includes all the files you need), you need a Flex Builder project. We thought about
using this option, but there are over 1,000 code samples in the usage docs and setting up
Flex Builder projects for each of them was just too overwhelming.
Thanks again for the feedback. This is the first release with integrated running samples
and it's great to see how people are using them
Also, I checked out the flex-docs.com app and it's pretty cool (and wicked fast!). Neil,
please let me know if there's anything I can do to help get it going with Flex 3 docs.
Best regards,
Randy Nielsen
Flex Documentation Manager
Thanks, Randy, for responding. I always try to keep my complaints constructive so that people might respond in a helpful manner -- especially when it's something that I use on a daily basis.
As for your problem with requiring over 1000 Flex Builder projects; I think that this might be an opportunity to get involved with the Flex Champion program. Having, say, 100 Flex Champions create 10 Flex Builder projects and compiling with the View Source option selected doesn't seem daunting. Adobe could even donate some Subversion repository space so that each project could be maintained for future versions.
Of course, then you'd be able to distribute Flex examples. I am also sure that there are other advantages to this scenario as well.
Just a thought.
examples couldn't be open-source, too. That said, there are a few wrinkles we'd have to iron
out first. The biggest one is that we pull the source code into the Framemaker files by reference
and having the .fm files and the .as files in different source control systems will take some work.
Also, the main reason we can pull running SWFs into the docs is that they're generated when we run
automated unit tests on all the samples. We need to ensure that the unit tests continue to work.
Also, I responded to Neil via e-mail asking for more info on his app. It could be as simple as
redirecting to livedocs.adobe.com/flex/3/langref
Thanks!
-Randy