Dan Herbert's

Up until recently, I worked for a transaction processor (company that processes credit transactions at stores). The 2 years working at this job made me aware of how dangerous credit card theft/fraud can be. As a college student constantly being warned about identity theft, this made me very paranoid about using a credit card for purchases.

As a result, I made a decision to use cash for purchases as much as possible, since you can’t become the victim of ID theft from cash. Although you definitely could become victim through other means, I figured this would keep me a bit safer, albeit at the risk of losing more real money in a mugging.

So for the past 2 years or so, whenever I made a purchase and got change back, I would save that change. I never used the change when purchasing stuff. I would always keep it, organized neatly by denomination. Today, I decided to cash in on my savings and see how much it was worth. Two years of purchases amounted to $174.53. This came from:

• $150+ in quarters
• $10+ in nickels
• $10~ in pennies

Just from saving small change when getting lunch and making other purchases over the years. All that money will come in handy when I buy my new Android phone next month!

Lately, I’ve been working heavily with the Prototype JavaScript framework. Since I’m new to Prototype, I’ve spent a large amount of time reading the documentation to ensure I’m doing things right. My frustrations with learning the new API led me to tweet about it a few times, which in turn, led to a response from a member of the Prototype team.

Most of my frustration came from the awkwardness of trying to learn a new API, however a good amount of it also came from what I feel is poor documentation. This post is a direct response to that tweet. I’ll cover what I think makes API documentation “good”, and what I feel makes API documentation “bad”. Since I’m partial to jQuery, I’ll be contrasting Prototype & jQuery’s documentation a lot. As a disclaimer I want to state a few things up front to make my biases clear:

• My JavaScript framework background comes from jQuery. I consider jQuery’s documentation to be what API docs should be. Understandably, jQuery aims to be a minimal API, so it also has minimal information to document. However, the spirit of its API design is what makes me prefer it over others. I’ll probably have another blog post about it in the future.
• The Prototype JS framework is huge. I find that there are a lot more utility classes & methods in Prototype than there are in jQuery. With the much larger API, I can understand how difficult it would be to comprehensively document the entire API well. My beef is not with the content so much as it is with the formatting. In fact, I would say the documentation is well written in most parts, just poorly outlined & formatted.

I want to be clear that I don’t intend this post to be a “Why Prototype sucks” article, or a “Why you shouldn’t use Prototype” article (I’ll save that for another day ;-p). I’m simply explaining and trying to justify the shortcomings in the documentation of the API. So here it goes, there are thing things I think it does poorly and how it could be improved. If I haven’t made it obvious yet, this is “My Opinion™”. All of “My Opinions™” have the potential to be incorrect, inaccurate, or maybe even downright snarky. I don’t mean to be offensive, just informative.

As a general overview, here are the things I’m going to talk about:

• Include working examples (if possible) in your documentation, and make sure your examples have the entire, complete, working code.
• Every time a method is listed, it should be listed using its signature, not just the name. This removes the question of whether something is a property or method without having to pay close attention.
• Format the documentation so it is easy to find the inputs, outputs, and what it does without having to look too closely.
• Take advantage of presentational elements in your documentation. Use contrasting backgrounds, different font faces, sizes, & shapes. Use positioning. Don’t repeat yourself.

Lack of great examples with working demos

This is something that jQuery does really well. Every method has a demo where you can see the method being used in a live demo. Below are pictures of jQuery’s children() method documentation page followed by Prototype’s equivalent method childElements(). Both API Docs demonstrate how to use the method and the scenarios. There are some major differences though:

• jQuery provides a working visual example. You can see the method working, so you can see what it will do before you use it. Although the specific method being demoed is pretty straightforward, there are more complicated methods that can really lend themselves well to this.
• jQuery allows you to get the complete working example. You can click the View Source tab to get the complete example code. This encourages you to play around with the demo on your own, tweaking it as needed. I can expand this demo myself to learn more of the “what if” scenarios of the inner-workings of this method. Again, although this particular example is simple enough, more complicated methods can really take advantage of this type of information. This is great for beginner programmers, or even academia where teachers can provide working demos to students without having to take the time to fabricate examples on his or her own.
• jQuery’s is more interesting! Prototype’s examples have what I’d consider very plain and boring styles. It’s all straightforward black & white. While you may consider this a good thing, it doesn’t stand out. jQuery uses contrasting colors. A much darker background for the code example makes it clear and obvious that: “This is an example!”. The working demo includes blues, reds, & blacks, as well as different font-faces. This makes it more interesting to read. I can personally say that after hours of coding and reading through documentation, the presentation of the demo makes a difference.

Ambiguous Method Notation

When showing a method in documentation, it should have parenthesis after its name. In almost every situation, this rule should always be adhered to. When I first started using Prototype, I was unsure of when Prototype uses methods and when it uses properties. Again, below is an example of what I’m talking about. This ambiguousness bit me a few times during development. When scanning the list of members of the Event object for example, I didn’t immediately notice that the X & Y coordinates for the mouse are methods and not properties. This made me waste time trying to use the methods like properties and then wondering why my code wasn’t working.

• The left shows part of jQuery’s event object sent in as the first argument of every event. On the page’s documentation, every method is followed by parenthesis. This is consistent throughout the entire documentation (except for the page name titles). In addition to appending parenthesis, the arguments are stated in every listing of each method, where applicable. If a method has a varying number of arguments, another good notation that could be used (although jQuery does not do this) is to write the method like this “preventDefault(…)” to show that the method has arguments without specifying what the arguments are.
• The right shows PrototypeJS’ event object and its methods. At first glance, it is unclear that these are all methods, or, which are properties and which are methods. Especially coming from jQuery, it can be unclear what is what. This is possibly my biggest annoyance with the PrototypeJS documentation.

Poorly Formatted & Outlined Class Definitions

Prototype gets this partially right & partially wrong. I like how the class properties are listed on the left, because it makes it easy to get to the details very quickly. However, the meat of the documentation is feels very devoid of helpful information.

• The fluid interface makes the documentation feel “empty” because the content stretches out to the entire width of the screen.
• Scanning the docs is difficult because the list delimiters are not clearly presented. jQuery gets this right by creating a different colored background for each method name, making it clear where one method ends and the next begins.
• Continuing from the previous section, method names are listed without their parenthesis. The actual signature is listed below the method name. This breaks the DRY (don’t repeat yourself) rule. The method name is listed twice. There is no reason why this can’t be combined into one line instead, so the arguments & return types are listed on the same line and the method name is only listed twice. jQuery also does a good job by making it very clear what the arguments are and what the method returns. It is easy to scan the entire document and find what you need.
  
  
• Lack of an outline on the page. Prototype does a good job of explaining what methods & objects are used for. The problem is the documentation can get lengthy (anything over 1 screen full is lengthy) and it lacks an outline. Every Wikipedia article includes an outline (which can optionally be collapsed) so the reader can easily see what topics are included on the page and jump to them as need. jQuery makes good use of this concept. Since jQuery’s documentation is powered by Wiki software, I imagine this is what drove them to use an outline in this way.
• Lack of well contrasted colors, fonts, and layout. jQuery makes good use of backgrounds, font-faces & styles, and positioning. The documentation is well structured and makes it easy to quickly scan the page to get what you’re looking for without having to go too deep or pay much attention. This is a time saver. I find myself having to carefully read Prototype’s documentation more often. Part of the efficiency in reading could come from just my comfort in using jQuery also.

In summary, I think the biggest mistake Prototype’s documentation makes is that it fails to make it easy to find 4 essential pieces of information about a method very quickly.

• Method Name (well… this one it does. It’s hard to screw this one up)
• Inputs
• Outputs
• What it does to the inputs to get its outputs

These 4 things may seem basic, but I’ve seen lots of documentation, including Prototype, jQuery, Microsoft, PHP, my own, and others somehow forget to include all of these aspects. As a rule, when writing documentation, these things should be made very easy to find out, should not take up a lot of screen real-estate, and should be clearly labeled & easy to find when quickly scanning the documentation.

Conclusion

Hopefully, this article doesn’t come off as attacking Prototype in a mean way. I don’t mean for this to seem malicious or hateful. I wrote this to outline what I feel are the good, the bad, and the ugly things about API documentation. I also wrote this because a Prototype developer asked what I thought I disliked about their documentation, and since he seemed nice, I thought this might help in their documentation overhaul.

I firmly believe that the thing that makes or breaks an API is not just the interface itself, but how well that interface is documented. This is one of the key reasons why I like developing with C#, jQuery, PHP, & Java. I find Prototype’s documentation awkward at times, and not very useful to beginners, which is important, otherwise you’ll scare away people who would otherwise love your API.

So hopefully this is a lesson for anyone developing an API, not just Prototype. Make your documentation awesome and you’ll get a bigger following!

It looks like the Prototype team has already started on a new version of their documentation. They’re using an automated tool this time to generate the docs. I don’t know if this would be a considered a good thing or a bad thing, but it seems to be helping them. It still breaks many of the “rules” I’ve outlined in this article, but it is definitely an improvement over the old look, with the exception of that annoying new menu!

I’m curious to see what others think about the Prototype documentation, or API docs in general. Leave comments!

A while back, I created a bookmarklet to make YouTube videos full screen, and get around Adobe’s awful decision to require full screen flash videos to always have focus.

Since that posting, YouTube has added the “pop out” button to all of their videos. My previous bookmarklet is now obsolete, however since other flash-based video sites haven’t made a comparable feature to YouTube’s I’ve made another Full Screen flash bookmarklet, but this time, it has to work in any flash video site.

To recap why I don’t use the built-in full screen button on flash videos, it’s because on a dual-monitor setup, flash must always have focus in full screen mode or else it reverts back to normal size. I want to be able to watch flash movies and do other stuff at the same time. To overcome this, I make the flash video expand to the size of the browser window and then use the browser’s full screen feature.

I’ve tested it in YouTube.com, TheDailyShow.com, blogtv.com, Vimeo.com, Viddler.com, TwitVid.com, and Hulu.com. The only site that doesn’t seem to work properly is Hulu (it “works”, but doesn’t go fullscreen), however, since Hulu has its own popup window button, this is not really relevant.

To get it, drag this link into your bookmarks toolbar. You can use this bookmarklet to undo the effects of the video embiggening if you want. When you use the bookmarklet, it will search the page for any flash objects that look like they are videos, outline the video, and add a link that will embiggen the video when clicked. To make the video full screen at this point, just use the full screen feature of your browser (usually F11). Unlike my previous bookmarklet, this will simply expand the size of the flash object on the page. It does this for reasons I’ll explain below.

Here is a breakdown of what the bookmarklet does:

1. Load jQuery from Google’s AJAX Libraries CDN. Since including jQuery within the bookmarklet itself seemed like overkill, this was the simplest alternative.
2. Once jQuery is loaded, the bookmarklet traverses the page looking for any object or embed tags.
3. These elements are then inspected to determine if they are videos. I don’t do anything very sophisticated to check if they are videos. All I do is check the height of the video. If the height of the video is greater than 250 pixels, then it can be assumed that the object is a video.
4. Create a “Go Fullscreen” element, which is positioned at the same location of the video. This somewhat difficult to do because of how flash videos render on the page in certain cases.
   Flash videos can’t be wrapped with a tag, because some flash objects’ height is not reported as their true height, so the wrapper would end up getting rendered behind the flash object in this case.
   Instead, I created a container element, checked for the “true” height of the video, and then appended the container element to the bottom of the page, and absolutely positioned it so that  it would appear to wrap around the video. This has worked well for all of the sites I’ve tested the bookmarklet on.
   I use the “external site” icon from Wikipedia for the “Go Fullscreen” link. Since bookmarklets don’t exist on any specific domain and I don’t want to host the image myself, I chose to hotlink to Wikipedia and hope that they don’t mind me borrowing their icon since it’s Creative Commons licensed.
5. When the “Go Fullscreen” link is clicked, any “Go Fullscreen” outlines on the page are removed. After this, the flash object is given a fixed position and made to have 100% height and width. In all sites I’ve tested this on, it works flawlessly (except for Hulu as stated above).My original approach was to create a popup and append a clone of the flash video inside the popup window. This didn’t work well because certain flash video players become upset when you embed them into an empty page. I never found out the exact reason (that would require me to reverse engineer minified JavaScript to be 100% certain), I can assume that it has something to do with other markup on the page that the flash video relies on, or JavaScript objects that the flash video needs to be able to call. The approach I chose instead is guaranteed to work because it never takes the tag out of the page and it never removes it from the hierarchy of the page, it just re-styles its look. That’s the magic of browser MVC! I only altered the view, not the model, so it works.
6. For undoing this entire process (in my undo bookmarklet), I store the ID  (the bookmarklet generates a unique ID if one doesn’t exist) and original state of the flash video element in the window object. When the undo bookmarklet is clicked, this state is retrieved and set back to the flash video.

That’s a rough breakdown of how the bookmarklet works.

I’ve published the source to the bookmarklet on GitHub for those who are interested in seeing exactly what happens in the bookmarklet or if you want to tinker around with it.

The bookmarklet was created on a Windows machine and uses a batch script that uses the YUI JavaScript compressor to prepare the bookmarklets. If you want to build the bookmarklets yourself, you’ll have to download YUI Compressor and make sure the “package.bat” file is configured to point to the correct location for the YUI Compressor.

Google recently announced their newest endeavor, Google Wave.

Google Wave is an open-source collaboration tool that combines wiki software, real time document editing, email/IM, and a few other online social networking niceties. At first I brushed it aside as something I would flop and fail like a lot of Google’s other social experiments. This seems to be the opinion of a lot of other people, including the creator of StackOverflow.com, Jeff Atwood who’s twitter comment about Google Wave actually made ZDNET’s news.

I shared the same feelings toward Google Wave at first, however after (perhaps) drinking too much of the Google Kool-aid, I’ve become convinced that this may be one of the killer apps in Google’s arsenal. The key is how it can be adopted by business, as well as regular people. Consider the following:

• Completely open source. Anyone can set up their own Google Wave servers, so businesses can feel free to use it internally with no security concerns.
• Communication tools. Businesses can use this to replace an Exchange server. I doubt anyone would actually replace exchange, but companies looking for something new  or companies that don’t have anything yet could definitely be convinced with this feature. I’m a huge Gmail fanboy because of how useful Gmail makes it to search, organize, read, and write emails. If this carries over well enough to Google Wave, this is a key feature.
• Wiki/document collaboration. Having documentation that can be updated in real time for any employee to see right away is a totally awesome tool! Wikis have been proven to be useful, so integrated with other packages, this is all the more enticing.
• Extensions. Maybe not a killer feature initially, but this is big. Much like extensions for Firefox, I predict this will be the piece that makes Google Wave truly popular. If Google Wave doesn’t offer something out-of-the-box, then it can be created as an extension so that there is nothing that you can’t do with it.

I’m waiting for more to be released before I’ll say it’s going to be a success for sure, however from what I’ve seen, this could be big. Google already provides a lot of tools and services for businesses. Soon they could be the next Microsoft, only you know… without the evil. Even though I’ve got to admit, Microsoft really seems to be trying lately.

I think Google Wave can succed with web companies that can use the (open) source to provide customized business collaboration solutions that they can produce very quickly since the code is already more or less complete. Since the solution would be open source, there would be commonalities among any company providing a customized Google Wave offering, spreading the brand, market, and mindshare of the product.

One of the things that really bothers me about Adobe Flash’s fullscreen mode is that it is very unfriendly to people with dual monitors. This problem stems from a stubborn “security concern” on Adobe’s part, which makes very little sense to me.

I understand the security implications of allowing flash to take over your entire screen. Adobe’s fullscreen mode rules are, for the most part, very well grounded in good security practices; however, for a dual-monitor system, this issue is not a security concern, it is a usability problem. Flash should not need to have focus to allow fullscreen mode when there are 2 or more monitors on a system.

All complaining aside, this issue has led me to explore alternatives to let me watch YouTube videos in fullscreen mode while doing something else on another monitor simultaneously. There is the hacker way of fixing this, which involves editing the flash plugin’s binary with a hex editor. This is too much trouble for me and most people, I’m sure.

Since I really only watch flash videos on YouTube, I only needed to have YouTube videos go fullscreen. This would be easy enough, I’d just need to get the URL of the .swf file and put it into the URL and flash makes the video expand to the size of the screen. The problem with this arises when you try to do this with YouTube’s new “shows” section.

Due to licensing, TV shows & movies on YouTube aren’t allowed to be embedded in other sites. As a result, pasting the direct SWF url into your browser makes YouTube think the video is embedded into another site and denies access to the video.

A better option is to use another one of YouTube’s new features, a video popup.

This popup page allows any YouTube video to be embedded. You just need to add a YouTube video’s 11-character unique video code to the URL of this popup page and you can watch any YouTube video. To make this effortless to do, I’ve created a bookmarklet that does all of the hardwork for you. Just add the link below to your bookmarks, and while watching a YouTube video, click this bookmarklet:

YouTube Fullscreen bookmarklet

Just click this bookmarklet while watching a YouTube video and you’ll be switched to the popup version of the video. To make it fullscreen, press the fullscreen key in your browser of choice (F11 on most browsers) to get a useful fullscreen experience.

Now I can watch Star Trek while doing productive things on my second monitor!

There is a classic episode of The Simpsons where Renier Wolfcastle is shooting a movie scene in a nuclear power plant and is given a pair of saftey goggles to protect his eyes from a tub of acid that is going to be spilt during the scene. During the scene, things go horribly wrong and Renier is swept away while saying “My eyes, the goggles do nothing!”
 

Google just released their own “goggles” feature in gmail labs, meant to ensure you do not send out a potentially regretful email late at night. The feature works by asking you to solve a set of arithmetic problems before you are allowed to send out your email.

The idea of being required to solve long arithmetic problems before being allowed to send emails is an awesome idea in my opinion. I recommend bumping the difficulty to level 5 if you want to try it. I set the difficulty to 5 to begin with, and given the simplicity of the equations at that level, I’d hate to see how easy the lower levels are.

I think I’ll have a lot of fun with this one!

Microsoft recently announced that the javascript library jQuery is going to be included in future Visual Studio 2008 releases as well as a patch/hotfix coming soon. In addition to this, Microsoft plans to offer full support of the API, including intellisense, and inclusing into its “shared source” AJAX Control Toolkit libraries.

For those who have never heard of jQuery, it is a Javascript library/API that has become very popular since it first came out. It focuses on the “less is more” principal, meaning that the API is very minimal, but it also allows developers to do more with less lines of code.

jQuery is run by John Resig, a man who really knows his stuff when it comes to Javascript. He’s responsible for the FUEL API in Firefox 3 and he’s very outspoken about the power of Javascript. Because of the knowledge of John, as well as the other developers writing the library, the API can do things other Javascript API’s can’t do, or don’t do as easily (in my opinion)

• Work totally fine side-by-side with other Javascript libraries, including different versions of jQuery, on the same page
• Allow for powerful plugins to be written to expand the functionality of the API
• Lightning fast performance
• Extremely effective DOM traversal
• Offer an simple, consistent, understandable core API
• Work consistently across every browser.

Due to an issue between Vista and Firefox, when doing development on localhost, Firefox has a serious issue with resolving DNS requests. This only happens on localhost, so this does not affect any development not being done on localhost.

The issue can only be described as “pages loading unbelievably slow” when localhost is being queried for resources under Vista.

Not to worry, however, there is a fix!

To fix this issue, you simply need to type ‘about:config’ into Firefox. You may get a cute disclaimer warning you to be careful. Promise you’ll be careful and then type the following into the filter:

network.dns.disableIPv6

Set this preference to ‘true’ by double-clicking it. Once this is set to true, your performance will instantly be dramatically increased.

I’m not sure if this is a problem on Vista or Firefox’s end, however Internet Explorer does not have this issue on Vista so my guess is Firefox is broken somehow…

I just took the annual ALA Web Developer’s survey. I missed it last year (I somehow didn’t notice it on their site,)  but this year I’ve contributed.

It allows A List Apart to gather statistics on the Web Development industry, which I think is an awesome idea, since I love knowing the state of my industry and what direction things are moving in with my industry.

Check it out!

Microsoft just released the results of its Windows Mojave experiment.

Windows Mojave is a marketing experiment Microsoft created to convince people that a lot of unwarranted negative press has been spread about Vista, giving it an undeserving bad name. The premise of the experiment is this:

Microsoft took average people and introduced them to what they claimed was a new operating system. Microsoft told these people that Vista was “Mojave,” which was a codename for a new Windows operating system. The created new packaging for Vista, they changed the Vista name to “Mojave” in the operating system, and showed people what it could do.

The result of the experiment was overwhelmingly positive. Average computer users (or so it seems like) seem to really like the new system.

I try to remain as objective as possible about Vista. I’ve read the good things and the bad things about it and I’ve tried it myself for a little while. Several people I know also use Vista and I’ve had to help them with their computers on occasion.

As an avid computer user, my experiences with Vista have been somewhat negative.

I can honestly say, as negative as people like to be about Vista, it is not so bad. It has a lot of good points to it. When I used it, I really enjoyed a lot of the features and changes made to the OS. You could say it is a decent OS. As I said, however, I have had an overall negative experience with Vista.

At a first look, to the average person Vista can seem “shiny” and have lots of cool new aspects that make it seem like a great OS. What I doubt Microsoft’s Mojave experiment would test is the long term satisfaction with the operating system.

The negative experiences I’ve had with Vista all come from long term use of the OS.

There are major memory and performance issues with Vista. I tried running it on a machine with 1GB of RAM (more than enough for an XP machine) and it could barely handle itself after a while. This is not just something I say because I saw the Task Manager chart show the system using large amounts of RAM. It comes from actual experience. I’ve tried running programs I normally run under Windows XP without a problem, and have been disappointed that Vista can’t handle itself when more than 2-3 programs are running. Admittedly, Vista should be slower on my old hardware, just like XP ran slow on my older computers that were upgraded from Windows 98. However, I put a lot of work into turning off features of Vista so that it was running at the minimum it took to run the system. I turned off Windows themes completely. I shut down all of the services I knew I wouldn’t need.  I made sure that nothing was running at startup other than what I absolutely needed (just the software for my trackball). With all of the “stuff” I turned off, I would have expected Vista to run reasonably well, however I was disappointed that I just couldn’t get it to go faster.

Aside from memory and performance, which can be forgiven since I lack modern hardware to test the system against, I have major issues with the Vista interface. The Windows Vista interface is absolutely the biggest flaw in the operating system. Out of every Windows OS I’ve used (and I’ve used every OS from Windows 3.1 onward) the interface of Vista has to be the worst.

From what I heard about Vista development, Microsoft hired a world class HCI specialist to give Windows a facelift in Vista. What came of it was in some ways better than what had existed in previous versions of Windows. In many ways though, Vista fails completely when it comes to HCI. Microsoft broke at least 2 fundamental rules of HCI with Vista:

1. When designing an upgrade for existing software, do not change what users are comfortable with. Seeing how Microsoft has 90% of the desktop market and Windows has such a huge influence in society, it is really disgraceful to see them completely change what everyone has gotten used to over the course of the last 10-15 years. This is something that Mojave doesn’t seem to show (for good reason). Users may think it looks cool and shiny, but once they begin using it for day to day tasks, in my experience people generally become frustrated trying to navigate around the Vista interface.
2. Keep your UI consistent across your entire system. This is a tough one to do. Windows is a beast of a project and it has a lot of different tools, applications, and dialogs included with it. To change everything over to the Vista “look and feel” is a major undertaking that has got to be hard to do. I can understand having a hard time getting around to every single thing Microsoft has developed, making sure it aligns with a new style guidline. What I can’t understand is how Microsoft failed to keep the Vista UI consistent. The average person would never think about an issue like this when a “new” OS (such as Mojave) is being demonstrated to them. That is the point. A user shouldn’t have to think “is this UI consistent?” It should just feel easy to use. If a UI is different in some part of a system, that means the user has to learn a new interface and remember it. Microsoft seems to have had a really hard time deciding what a menu should be like in Vista. Every program you open has a different menu, different names for commands, and just looks different depending on what you’re using. This is where Vista fails the most.

If it weren’t for the UI issues with Vista, I’d be able to proudly say it’s a good OS that I’d recommend to my mother. However, when you’d be required to learn a new interface just to use your computer for basic things, it becomes something I can’t recommend to people who just aren’t computer enthusiasts.

I’m glad Microsoft tried the Mojave experiment. Hopefully it will show people that Vista isn’t as bad as everyone says it is (it has its merits.) It still doesn’t address the issues with Vista, however it might help fix Vista’s bad name