Quick start guides and in-depth API documentation

Documentation and the importance of it was touched in previous post. Since poor documentation is the most common reason to ditch your API and go for the alternatives, it deserves to be discussed thoroughly.

Even though the title gives the impression that it’s a question of selecting which direction to take or confrontation between the two, it does not have to be that way. It’s not a question of either or. Getting started and good API documentation can and infact should coexist and support each other.

We’ve all read tons of API documentation. Sometimes the answers are easy to find but not always. From my experience great API documentation is not that common. Too often API documentation is a list of features with minimal descriptions, it’s not in sync with the implementation or just plain hard to access.

Why documentation is avoided?

There’s reasons why documentation and manuals are not used. According to research people prefer to solve their problem by asking a colleague or experimenting on their own instead of reading documentation. Reasons to ditch online documentation are related to

• difficulties in navigating documentation,
• particularly difficulties in finding useful search terms,
• and disappointment in the level of explanation found.

Thus you should make sure your documentation tackles at least the mentioned usability problems.

Rely on peer developers

Asking peers for advice is also the reason why for example Stack Overflow (SO) is so popular. This brings us to an interesting opportunity. If the use of Stack Overflow is taken to the extreme, your API documentation could be based on the questions and answers in there. SO provides nice search function and quality of the answers is handled by the community. You can see the reputation of the people who provide answers. Thus you can easily evaluate how much you will trust the answer and is it worth anything. If your documentation sucks, it’s more likely that API consumers will look for help from SO. They might do it anyway especially if they have a problem with your API.

Thus it might raise the question, why do we put any efforts in maintaining poor documentation if it is hardly ever used? In addition to that you should seek answer to the question: what is the role of our detailed documentation vs community driven QA platforms? What value can be provide with the documentation that can not be provided by the community?

Modern APIs are expected to be taken into use as self-service. API consumers expect to find all needed information to work with your API without sending emails to you. Your duty as API provider is to offer excellent support from first encounter to replacing your API with another one. In this customer lifecycle API documentation and quick start guides have a slightly different but equally important role.

What is the difference?

What’s the difference with profound API documentation and quick start guide? Quick start guide is in essence a shortened version of a documentation, a useful reference, meant to make prospect API consumer familiar with the product as soon as possible. Often quick start guide contains less details and contains more complete code examples how to do specific fundamental operation.

API consumer needs to get first positive experience with your API fast, otherwise they are tempted to look for alternatives. This is where getting started type of content becomes your saviour. It gives the API consumer a glimpse of how things work without drilling into all the details and opportunities with the API.

Quick start guide is in essence a shortened version of a documentation, a useful reference, meant to make prospect API consumer familiar with the product as soon as possible.

What is quick start guide?

You might think that getting started is yet anothor separate document. That might be the case sometimes, but it does have other kind of forms too. There’s no single format or use case where quick start packages and guides fit best. Let’s have a look at some use cases and examples.

Console-alike instant playground

It makes sense to to offer quick start with the core functions and features with your API. Those features are used by majority of the API consumers and offering easy and fast instructions to jump in to your API is good customer service. Great examples of this are well-known Stripe and Pusher. Both offer getting started content in the (website) frontpage by providing instant try and learn console-alike playground. API consumer does not need to go anywhere else or download anything. They can just “click and execute“ to see how things work. Of course the approach has limitations since normally the examples are simplified, sometimes even to the extreme.

Reference apps

Another option is to provide sample apps, which extend the live console approach towards full applications. To see how API is used in simple app, probably enables faster knowledge transfer from API provider to API consumer than any detailed documentation could do. It’s not uncommon to provide client and server reference apps as open source. Twilio offers working client and server skeleton apps as quickstart guide in several programming languages. Each quickstart package contain short descriptions of steps to take before jumping to the code level examples. Code licensed under MIT and related readme is provided via Github.

Then there’s more options which are discussed in details in forthcoming book “Build for Developers — Application Developers as Customers in API Economy”

After getting started…

Your tasks as API provider is to make consumer’s journey with your API as easy as possible, that includes fast successull usage of it (quick start guides). If you manage to enable easy first success with your API in minutes, it is more likely that developer will go deeper. In business language you have now prospect, not just a lead.

Now that the API consumer has been hooked with easy to try quick start guides and consoles, it’s time to go deeper. This is the moment when profound and uptodate API documentation becomes handy. The API consumer already knows how to use authentication and use core value adding features of your API. The commonly used features sometimes is enough for the developer and there’s no need to look at your documentation.