Adobe Livedocs: A World of WTF.



  • Sorry for the long post, but some very juicy WTF's follow.

    I have always hated the Livedocs because they have been "slow," but not until recently, when I was trying to dynamically link to Livedocs pages for a school project did I look into the code and figure out the reason.

    They seem to be built using Quadralay's [link=http://www.quadralay.com/ePublisher/]WebWorks ePublisher[/link], which I guess converts between many forms of documentation. To be fair, I must be no easy task shifting huge help files to a web-based medium, but the solution generated by ePublisher is horrid, to say the least.

    For an example, go to:

    [link=http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/js/html/wwhelp.htm?href=Part1_Getting_Started.html]http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/js/html/wwhelp.htm?href=Part1_Getting_Started.html[/link]

    Here are only some of the things I can see are wrong...See if you can come up with any additional ones:

    1) Upon visiting the page, close to a [i]megabyte[/i] of external files are loaded, most of them JavaScript files. Not only is this a ridiculous size to download for [i]any[/i] single page, the fact that most of it is source code makes me shudder to even think about what is contained therein.

    2) On my 6MB/s connection with Firefox pipelining on, it still takes 20 seconds to load the page.

    3) Clicking on "Search" and typing in "Movieclip" causes another [i]530[/i] JavaScript files to load, all named "search2s.js", "search261.js" or similarly, totaling another [i]4MB[/i] and 2 minutes to even get my search results. Granted, Movieclip is a pretty common term in flash, but what's wrong with a simple database query and a results page? I can't even imagine trying to use this system on a dial-up connection.

    4) Looking at "files.js", it seems that a database query was asking too much--help topics are stored in JavaScript files by statically passing to a function the title and target html:[code]P.fA("Getting Started with Flash","Part1_Getting_Started.html");[/code]

    5) "title.js" has only this code in it: [code]document.writeln("<title>Flash 8 Documentation</title>");[/code]

    6) Looking at other JavaScripts, there is scads of hard-coded innerHTML string-building (I don't think they use createElement or appendChild anywhere). Few of the JS files are included by default, but the rest are added by document.write()ing hard-coded script tags. I found a div with a table in it, built completely with strings and variables, using about 150 lines of string concatenations (HTML += "...).

    7) Oh. My. God. In "outline.js", JavaScripts, [i]themselves[/i] built with strings line-by-line, are THEN added to the page using document.write(). And to top it all off, the comment above this reads "// Define accessor functions to reduce file size". Well, they were decreasing readability and manageability ten-fold, but at least they reduced the filesize of the code to a measly 4MB.

    8) Uses frames. 'Nuff said.

    9) Hmm...another useful JS file: called "towwhdir.js": [code]function  WWHToWWHelpDirectory()
    {
      return "";
    }[/code]

    10) A reader's comment on the page I linked to reads "Cannot open live docs, tutorials. I have Mac OS10. What to do?". The response from Adobe staff is "There is a known issue with opening LiveDocs on some Macs, which is currently being investigated by the engineering team. Please open LiveDocs using whichever method you used to comment here (either by opening a new browser in Firefox or Opera, or by fully closing LiveDocs and browsing to it manually)." You mean what they're doing isn't compatible across multiple browsers? I can't imagine why!

    I could go on, but I picked out enough WTF's for one day. This is simply the worst online documentation I have ever used.

    Needless to say, I failed in being able to link to Livedocs pages directly, instead opting to parse up the [link=http://www.adobe.com/support/flash/action_scripts/actionscript_dictionary/]ActionScript Dictionary[/link].



  • Wow. That IS terrible. So ... much ... Javascript .... /whimper.

    At least when you grab the hard link at the bottom of a page, it only takes 10 seconds to load up :(.
     



  • @boolean said:


    5) "title.js" has only this code in it: [code]document.writeln("<title>Flash 8 Documentation</title>");[/code]

    Very enterprisey!

    I've been searching for "Movieclip" since I read that part, and it still hasn't finished loading. I'm not sure what speed my network is, but it's a corporate one for a rather large corporation..



     



  • I hope Adobe asked for a refund.



  • Hi all,

    My name is Randy Nielsen and I currently manage the Adobe Flex and ColdFusion doc groups. I (with a lot of help) wrote the first version of LiveDocs back in the Allaire days and have been closely involved with it ever since.

    Here's the deal: After the Macromedia - Allaire merger, we got real developers to rewrite the infrastructure and then started posting Macromedia products on LiveDocs. However, we wanted them to be searchable and (as you correctly guessed) the quickest way to searchability was through WebWorks Publisher. Obviously this solution isn't scaling very well for large docsets.

    We're working to remediate this problem. For starters, compare the Flex 2.0.1 search with the Flash 8 search: we now use the website's Google appliance, which is a lot faster. We're also looking into a completely new way to drive the TOC (still JavaScript, but a lot lighter) and hope to use that for all new products (and hopefully redo a few old ones, too).

    I just wanted you to know that we realize the LiveDocs JavaScript circus is suboptimal, and that we're working to make it better.

    Regards,
    Randy Nielsen
    Flex and ColdFusion Learning Resources Manager
    Adobe Systems Incorporated



  • Sweet merciful christ.

    Is the sentence "After the Macromedia - Allaire merger, we got real developers to rewrite the infrastructure" supposed to be sarcastic?



  • @jrunrandy said:

    ...we realize the LiveDocs JavaScript circus is suboptimal...

    HAHAHAHAHAHAHAHA!!!! Assuming that the original post and subsequent follow ups are accurate, that's the understatement of the day. Calling that "suboptimal" is like calling the sun "warm" or the Atlantic Ocean "a bit wet".

    I hope that you're all very very sorry for the tragic evil you have unleashed on the world.



  • Well, as has been discussed many times before on this site, WTF's are brought about in various ways, often because of corporate pressure or lack of time/money to do things the right way. I appreciate the explanation from Randy, and am looking forward to a more streamlined version.

    From his post, it seems to me that Macromedia/Adobe is not so much to blame for the JS madness as much as Qualdralay's product is, but I'm not sure how much it was modified. Either way, it was a good exercise in code analysis =)
     



  • As I wondered what happened down there, I opened firebug's network debugging.

     And then, oh no. My eyes melted into my own throat so I couldn't scream.

    This is so priceless I felt obliged to try screencasting that incredible cataclysm. Worse than failure, oh yes it is.

    So here is the adobe livedocs network debug screencast

    ( my apologies for the format, this is the output producted by vnc2swf, this is my first try. I'll try to convert it to another video compression )



  • @aikii said:

    ( my apologies for the format, this is the output producted by vnc2swf, this is my first try. I'll try to convert it to another video compression )

    VNC2SWF is just fine, thank you. If you want to process it in the future using a more video-y codec, you can use vncrec instead and pass it through transcode, ffmpeg, mencoder or whatever. (Probably saving it to something MPEG4/H263ish, and then wrapping that in FLV...)



  • @kirchhoff said:

    @aikii said:

    ( my apologies for the format, this is the output producted by vnc2swf, this is my first try. I'll try to convert it to another video compression )

    VNC2SWF is just fine, thank you. If you want to process it in the future using a more video-y codec, you can use vncrec instead and pass it through transcode, ffmpeg, mencoder or whatever. (Probably saving it to something MPEG4/H263ish, and then wrapping that in FLV...)

    I realize the size is fair since I kept the rez to 1024x768. Should I want smaller dimensions, I'd better reduce the desktop size to keep fonts readable ( the display is purely virtual since it's Xvnc ), or at least crop irrelevant parts.

    I still have some issues with both vncrec and vnc2swf->mpeg coredumping, but I don't think I'll bother any longer. I figured I could send it on youtube but it's going to be awful. Unreadable screencast is useless.



  • It's hilarious to see how the major software publishers themselves can't get it right.

     Reminds me of "solution providers" whose corporate sites are full of broken links ...


     



  • @joblini said:

    It's hilarious to see how the major software publishers themselves can't get it right.

     Reminds me of "solution providers" whose corporate sites are full of broken links ...

    I think you're forgetting that it was not that long ago that Adobe merged with Macromedia, and only at that time did adobe get real developers.  Most of the livedocs is not that bad, and as was mentioned is using a better platform, but apparently flash docs are a bit of a wtf (as is Flash itself).  Don't blame Macromedia for Adobe's fuckups in the past.  They are doing the best they can maintaining the legacy app.  Once they get a chance to rebuild it, it shoudl be much better. 

     And hey, at least they didn't code it in ASP or .NET.  Now that would be a maintanence nightmare...



  • I worry about the fact that there seems to be dozens of Javascript files that are exactly 147 bytes.



  • I felt a remorse : after all, the keyword I typed yielded more than 100 results. Not exactly unfair: it's worth asking why adobe needs 600+ requests to fetch about one hundred links while others just need one for the same result.

    So I tested it searching for a non-existent keyword. Result : 0 pages found, 643 requests. Doh !!!

     The network debug screencast has been updated accordingly ( the python version of vnc2swf works even better, producing a file about half the size ).

     About the fetched javascript : "search2s.js" seems to execute some client-side update, but the fact it has to be fetched every time is ridiculous. I checked my proxy's logs : nothing is cached, every single file is remotely fetched, some files are fetched thousands times with exactly the same content ( Oh, I forgot : "10 KB from cache". Well thank you, the 2520 uncached kilobytes seem lighter, now ).

    Looks like they want every single javascript line to be fetched before execution. He, is it some kind of distributed computing ?! Where is the AJAX-enabled SETI program ?

     btw I just read this Google : Ajax is about abusing standards. I wonder what adobe is about ... 

     



  • @russ0519 said:

    And hey, at least they didn't code it in ASP or .NET.  Now that would be a maintanence nightmare...

    Why?

     I'm working on a fairly large ASP.NET app. I made a few design WTFs early on, but they're mostly corrected now, and it's a dream to maintain.
     



  • @bobday said:

    @russ0519 said:

    And hey, at least they didn't code it in ASP or .NET.  Now that would be a maintanence nightmare...

    Why?

     I'm working on a fairly large ASP.NET app. I made a few design WTFs early on, but they're mostly corrected now, and it's a dream to maintain.
     

     

    That's gotta be sarcasm, there's no one out there who really thinks javascript is easier to maintain than .NET... right? 



  • @aikii said:

    As I wondered what happened down there, I opened firebug's network debugging.

     And then, oh no. My eyes melted into my own throat so I couldn't scream.

    This is so priceless I felt obliged to try screencasting that incredible cataclysm. Worse than failure, oh yes it is.

    So here is the adobe livedocs network debug screencast

    ( my apologies for the format, this is the output producted by vnc2swf, this is my first try. I'll try to convert it to another video compression )

    Am I the only one who was looking at the time remaining and the number of objects, and was hoping it'd stop at 666? And it was so close, too!  



  • @rbowes said:

    Am I the only one who was looking at the time remaining and the number of objects, and was hoping it'd stop at 666? And it was so close, too!  

    ahah, excellent. If it came to my mind at the time, I'd have tweaked it a bit to show the number of the beast.



  • @Cap'n Steve said:

    I worry about the fact that there seems to be dozens of Javascript files that are exactly 147 bytes.

     If I saw that correctly, it was actually one file, search2.js, loaded numerous times. It almost seemed as if once a searchXXX.js file was loaded, it would be "searched", and if it didn't return a result, it would reload search2.js which would then load another one.

     
    Scary.
     



  • Maybe I'm missing something, but after a little browsing around (oh, and by the way: I'm on Mac OS X, and it worked for me -- after it stopped in mid-load and I restarted) I was unable to find [i]anything[/i] which actually needed JavaScript, other than the collapseable directory view in the left frame. All the rest of it could have been implemented much more simply using... well, using almost any technology: SSI, CGIs, ASP, Java Servlets... Maybe I'm just missing something, but it certainly looks to me as though 99% of those files are reinventing the wheel, at a tremendous cost in bandwidth and maintenance.



  • I almost forgot what is said in the first post, that the documentation seems to be generated by webworks.

     Now, just imagine the backoffice part. Where the hardworker coming back home, exhausted, but proud to say "YES ! This week, I was able to add a comma to the documentation without having to reinstall the whole server".
     

    Ok, who's gonna try it ? It'll be ready for the next time someone deserves punishment ...



  • @aikii said:

     btw I just read this Google : Ajax is about abusing standards

    From that article;

    Before Google Maps, the Internet world was a flat place without dragable maps and without online mailboxes that looked like their desktop counterparts.

    Nobody has heard of Outlook, evidently. ;-)



  • @The Vicar said:

    after it stopped in mid-load and I restarted

    Just noticed that this was ambiguous. I meant "after the page stopped in mid-load and I reloaded the page from scratch", not "restarted the computer."



  • Ebay's API docs have been in a very similarly sluggish format for several years.

     



  • the flex docs do seem zippier, for the search though there needs to be an advanced search, not just the google site:blah.com

    live docs are a nice idea though, and actually the help files within the IDE run very fast and are very helpful just those old live docs are insanely slow

    http://livedocs.adobe.com/flex/2/docs/wwhelp/wwhimpl/js/html/wwhelp.htm?href=Part1_GetStarted.html

     



  • @merreborn said:

    Ebay's API docs have been in a very similarly sluggish format for several years.

     

     Duh. Looking at the network requests, that's the very same software. A whole world of search2s.js spawning like agents Smith.
     



  • A little update, though. Ebay's setup seems to run far more smoothly. Adobe probably runs another version, or their configuration is WTFed.

     For the record :


    A search on adobe docs produces 548 requests on firefox, and 280 on IE.

    A similar search on ebay docs produces "only" 34 requests on firefox, and 13 on IE.

    this has to be a misconfiguration problem.


     



  • @aikii said:

    spawning like agents Smith.

    Oh dear.

    I wish for this to become a standard expression, or some kind of programming antipattern.



  • I noticed that big in the article too and I was wondering if it was just me that was confused by it.

    Before Google Maps, the Internet world was a flat place without [...] online mailboxes that looked like their desktop counterparts.


    WTF? O_o



  • I wish I could rate this at 10 stars, but alas, we have but a 5 star system!

    More than 600 requests and 3 megabytes to return ZERO search results? The developers behind that project should just quit, now. Just give up. They are the the scum of the programming world. It's the most enterprisey thing I've ever seen in my entire life, and it makes me sad to know that those POS programmers probably make the kind of money that is an order of magnitude more than I do. May God have mercy on their souls.



  • @jrunrandy said:

    Hi all,

    My name is Randy Nielsen and I currently manage the Adobe Flex and ColdFusion doc groups. I (with a lot of help) wrote the first version of LiveDocs back in the Allaire days and have been closely involved with it ever since.

     
    Thank you for the prompt and frank explanation.  That sort of thing seems to be pretty rare, especially from a vendor to a public forum.

    --Mike


     


Log in to reply