All is not gold that glitters, especially with API docs

I saw some buzz about the Nest developers’ API explorer and its corresponding developer documentation so I took a look. For many reasons, new API documentation formats attract a lot of buzz (and envy) among technical writing circles. From the technical writers wondering, “How can I make my documentation to look like this?” to the executives demanding, “Why don’t our docs look like this?!” Rarely, do I hear, “should our docs look like that?” But, that’s what I’m here for (it seems).

Should your API docs look like the Nest developers docs?

The answer is, of course, maybe.

I don’t have any inside information about why or how the writers of the Nest documentation did what they did, so the following analysis is based on my observation and inference.

What it does well

It has a very clean UI. Clean presentations inspire confidence and professionalism.  The styling is consistent and aligned with the consumer site’s branding, which implies they consider their API docs to be a part of their brand promise. I think that’s a good sign. Externally, it shows that the company considers the API to be part of the product’s brand and not a bolt-on or afterthought. As a developer, this is reassuring.

As first impressions go, it has a very nice curb appeal.

The Home page provides clear paths to where you want to go next.  This is a good mix of value proposition and audience guidance to next steps. As developer home pages go, this is as good as it gets. It has a look that will not frighten non-technical people and information that a technical audience can bite into.

The developer docs start at Getting Started. They seem to expect the bulk of their audience to be new to the product by starting at getting started instead of some other type of overview. Given where the product is in the market, that seems reasonable.

The getting started content guides readers in various directions that seem to address a range of reader abilities and experience.  The content takes a bit of work to navigate. Not bad, but not seamless. The page could be improved with some introduction, besides text about how wonderful the site is.

The Nest Developer program provides all the tools you need to design, develop, market, and launch your Works with Nest product.

I’m sure it does, but this doesn’t help me navigate your page. If this is the getting started topic, let’s get started! I would expect to see a list of steps to help me get started here. Part of the momentary disorientation comes from the fact that the menu links, page title, and topic content don’t agree. The getting started content appears on the documentation landing page, eventually, so all is not lost, but the content is not as slick as the visual design, and the home page, unfortunately.

The API explorer looks cool, but I’m not sure how useful it is for anything beyond a marketing and promotion tool. Being a marketing and promotion tool is not a bad thing, especially when you’re trying to attract developer attention. This provides potential developers with a way to peek at the internals without having to go to all the trouble of getting an account, creating lots of code, etc. What it does, is help potential developers decide if they DO want to do all that.

However, as a documentation tool, I don’t think it’s very helpful. If I were developing with the API, I’d have my own cases and Postman console running which is likely to provide the same information, but personalized for my specific project.

The Codelabs and tutorials are very good. These seem to have received a lot of attention and are exactly where you need to spend your energy when trying to attract new developers. Lots of recognizable use cases and guides such as 10 tips for your successful Nest integration to help improve customer success are key to making developers successful quickly.

Where it slips up

Its localization has a few holes in it. I’m working on a bi-lingual app and my browser tells all the sites that care that I prefer content in Spanish. It makes testing my app easier (as it uses the browser’s language preference as an indication of how to display the content) and it provides some interesting web browsing experiences. In this case, some headings and menus are in Spanish, while the bulk of the text is in English.

Oops.

This, however, is not uncommon, as I’ve found out. This is often the result of merging content and publishing systems, from what I’ve seen. Not the end of the world, but it stands out in an otherwise clean UI.

The API reference seems autogenerated and almost not worth publishing. This is the type of API reference content that gives API reference content a bad  reputation.

For example, these descriptions from Smoke+CO Alarm reference :

  • software_version: Software version.
  • structure_id: Structure unique identifier.

show that some vexing documentation problems still remain to be solved, such as, how do you document an element that is, for all practical purposes, self documenting? Fortunately, they point out that the legal values of a Boolean field are true and false.

I totally get where this type of API reference content comes from, but we (technical writers, academics, and developers) still have some room to improve on this.

Error messages also seem to be autogenerated. Initially, I was excited to see that the error messages got their own page. Error messages should be self explanatory, but it’s very helpful to know what some of the messages’ back stories are, but such is not the case here.

The error messages include such helpful content as:

Cannot change Away state while emergency heat is on

The product tried to change the Away state while Emergency Heat was on.

Thanks.

Is this an example to emulate?

The attention to detail displayed at the beginning of the user’s journey through the site is certainly a good model to follow. Accommodating multiple audiences from the start and providing attractive tools like the API explorer and Codelabs can help if that’s where your product is in the market.

But, scratching below the surface is disappointing. It provides a lot of information for how to get started but not so much for how to actually finish (i.e. providing the information necessary to debug those vexing problems that show themselves as you get close to shipping). Having not used the API in a project, I can’t speak to the actual developer experience of this API, but I’ve see where this type of documentation (e.g. skimpy API reference topics) can lead you a long ways down a dead-end path before you realize it’s a dead-end.

The fact that they did such a great job on the home page and tutorials makes the lame API reference seem even worse by comparison. If you want to emulate it, emulate what they do well, if that’s what your product needs.

  • Working with a designer to create a gorgeous and functional home page doesn’t require any advanced technology but can certainly improve the new user and potential user’s experience.
  • The API explorer looks sexy, and could probably be emulated with some clever CSS.
  • API reference should be more than “the system_id is the ID of the system.” Empty boilerplate topics are still a waste of everyone’s time.

Leave a Reply