Organization

When done correctly, this is a great tool.

The idea here is that there are multiple scrolling panels; that are either loosely, or quite tightly coupled together.

Often the left-most panel contains ways to group your API. For example, the grouping might be by functional area within a company. Things like Inventory; Accounts Payable; etc.

The middle scroll list would contain the API endpoints that deal with the area or topic that was selected from the first list.

Then the right-most scroll list would be detailed information about the endpoint selected in the middle, like the HTTP methods used by the endpoint, or other parameter info. 

As the user picks from ANY of the lists, all of the lists are supposed to stay in sync with each other.

Sounds useful, right?

Well, in practice, it can turn out a little less useful.

For instance, different platforms like Windows, Mac and Linux handle how the scrollbars work a little differently. On Windows, if you tap/click in the scrollbar background, the scroll list will move down "a page" worth but on Linux it will jump to that relative portion of the list (see video 1).

On long lists, this difference is magnified.

..and, as you might now expect, the backend "list syncing" code does not always keep up; and throws the actual end user all over the place.  

The user can easily lose their place in the list; which is frustrating because the lists are often the main way (or only way) to access the actual endpoint docs.


There are a number of other usability issues to be aware of on these lists; like how the top of the scrollbar can scroll up under pinned navigation bars, making it impossible to get to the tops of lists.

Some users change in the operating system settings how far a list moves when clicking the scrollbar, or its up/down arrows -- which just adds to the list-management fun.

The bottom line is, if joined scrolling lists are to be your main way to communicate your API to end users, then you'll want to double or triple up on testing them. Include the main OS platforms in your ongoing tests, as well as the main usage types (desktop, web, mobile).

Types of Developers

There are different types of developers who will want to use your REST API; and they will have differing needs.

It is a big task to try and cover all of these needs at first, so you will need to understand who your most likely users are; and concentrate your time and energy (aka 'funds') in the right areas.

Here are some common types of developers:


The RTFM Developer Type

The Read The Fabulous Manual (RTFM) type. These types of developers appreciate complete, error-free documentation. They prefer to print and take the manual home (or will scroll through much of the docs on a device); before really trying to code anything.

These folks tend to be the ones that newer developers will turn to for answers, in time. It behooves you to have GOOD documentation for a RTFMer in order for them to become quickly effective.

Obviously, a RTFMer will also be the first one to point out errors or omissions in your documentation – so it is helpful to have at least one or two RTFMers on your own staff. That way you will have the best chance to catch documentation errors before your actual customer-developers do. This also helps to reduce customer support incidents; as the customers will have the best possible documentation to refer to at all times and will ask fewer questions.


The Examples Developer Type

Example Types do not need or want a stinking manual to start.

They want to dig right in using code samples.

An Example Type will have a Hello World app running against your API before they even receive your "Thank you for signing up!" email.

The Example Type might tackle your samples in differing orders, based upon their interest, or their need, at the time.

The documentation needs of an Example Type are different in that they need to support someone with immediate and all-over-the-place questions. 


Building-block style code samples are very important for the Example Types. See code samples below for some thoughts on how to do this.

Providing intelligent hooks from the documentation back and forth to the corresponding free-standing, code samples will help to get the Example Types up and running fast.


The Visual Developer Type

Actually a spin-off of the Example Type, Visual Learners prefer to watch actual videos of other developers running through the setup and usage of the API.  If you are going to have example videos, then bite-sized video portions of the setup, along with a few start-to-finish videos, is a good way to go.

The bite-sized videos can be added to the information done for the example types. They will appreciate it as well.

The start-to-finish video won't be that difficult because all of the component pieces would already have been done for the smaller videos. AND, everyone will appreciate the videos over time as quick freshers.

Finally, the bite-sized videos can be used in the marketing of your APIs too.

API Docs

This will sound like common sense, but you'd be surprised how often it is not true.

There are all kinds of reasons given when they don't match.

• "A 3rd party vendor is used to push the code CI/CD; but doesn't update the online docs."
• "The online docs are from a prior API version. Talk to the writers."
• "The code was done offshore and the documentation always lags behind."
• Shrug. "You know that developers hate to do documentation."

As a customer (ESPECIALLY a New customer who is evaluating your API) it is very frustrating to be trying to call an API with mismatched docs.

This also reflects on your company itself.


Spell things correctly.

It's bad enough when the documentation text explaining an API has spelling errors.

It's even worse when the API endpoints themselves have spelling errors.

It does not engender developer trust in the API endpoints working correctly, if even the endpoints or parameters themselves are spelled wrong. Having your code done offshore is not an excuse for spelling errors, poor phrasing, or bad grammar in either the API documentation or the code itself.

Code Samples

Just to point this out, another way that you might be able to introduce new users to your API, would be to have them create a simple Client. This Client would wrap up your endpoints in a way that most benefits the user.

figure 2: The API stack

Figure 2 illustrates this.

At the base of the figure is your own backend systems. This includes your databases, gateways, firewalls and applications that your API endpoints interact with.

On top of this is your published API, that describes the endpoints used to access your backend systems.

Your users can either (A) call your endpoints directly or (B) can use a separate client to access your API indirectly. 

The Client may do things like aggregating several of your endpoints into fewer actual calls –  calls that better fit the end user's workflow.

The Client may also pick and choose to include only those endpoints that the user will actually use most.

Creating this client will make it easier to incorporate your API within the actual user application itself.

Now, YOU can create this client for the user, or perhaps you can provide simple examples for the user to do so – as a way to help new users to learn their way around.

Each set of new users from a given customer can be walked through creating "their own" client; that they then get to walk away with and use.

Customer Support

Protect your User's Privacy

You may have heard the phrase "If a thing is Easier for your users to do; then it is harder for your developers to do".

The Easier an application feature is to use; the Harder it will be for
your developers to create it.

Anonymous Developer

This really just means: if you want an easy to use, intuitive system, it takes more effort.

I'd like to add a new phrase.

The easiest and cheapest support tools for the API vendor, may sacrifice the privacy of your users.

Me

And this really just means: Before you are sold on using a bunch of centralized, third-party support tools, like forums/team communications/bug tracking/feature tracking/etc, think about pulling things in-house.

There are many reasons why.

Here's a few:

It's one thing if hackers / or a bug / or an outage hits your own servers.

It's another if they hit a centralized service and whack you and many other companies, from a distance. Especially since you are then at the mercy of that third party to fix the issue. And if that issue is releasing your customer/user data; well, then you are largely out-of-luck.

There are other issues that can affect your user's privacy. Including the very TOS (terms of service) from places like Google; that grant themselves the right to process any of the information in your user's email if they interact in any way with Gmail. Even if the user does not use Gmail themselves!.  

It is advisable to put someone on actually reading these TOS, along with any updates made to them over time. It may surprise you what you agree to under these TOS. 


It is troubling to see API sites that force users into using Google services  and many centralized widgets like discussion forums, ticket systems and so on, knowing that any one of them can and probably will compromise the user's info in time. And that this will be out of YOUR control – even though you will take the heat for it.


There are alternatives to MOST of these centralized services, includes ones that you can self-host.

Lavojo is one site that helps with picking the best self-hosted alternatives for your company.

Developer Feedback

Practicing Active Listening...

I ran into one company that had problems with their users understanding their API docs. Notably, this company also suffered from the Wheel of Confusion (figure 1) and API→Documentation-mismatch issues as well.

It turned out that they just did not care hear what their customers were saying.  There was no real system in place to capture customer feedback or to reasonably deal with it. The existing <air-quotes>system</air-quotes> was a helter-skelter, mish-mash of email snippets and screen grabs, loosely managed outside of development.

For example, they had me look into one customer issue with the API docs, that had been awaiting an answer for TWO Months. The company had interacted with the customer over the issue; went back and forth on it a bit; and then just left it unattended for that long.

You can just imagine how pleased that that customer was.


Take and Act on Feedback

Your customers will want to help.
They will want to offer ideas or better ways to approach things.

Don't shut them out.

Have an accessible, monitored, system in place to take customer suggestions and other feedback.

Respond to the customer right away and let them know the status of their request, if needed. Don't make the customer continually ask. Have an online way for them to check on their own.


Going The Extra Mile

Level 2 here would be to proactively go after feedback & suggestions.
Have small games, prizes or awards for helpful suggestions.

Write these up in a blog, mentioning the helpful customer by name. Show the prize that they won.

You *will* get useful feedback and increased leniency from your customers on those things that can not be immediately addressed.
    
#Leniency from customers is much better than #animosity.