Dan Herbert's

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!