How to Make API Documentation Better with this one Metric.

We are building LiveAPI an API documentation product. With LiveAPI, developers can instantly try your APIs from the browser. It helps to capture their attention and convince them that it works fine. If you have any OpenAPI specs or markdown descriptions you can use LiveAPI to generate interactive docs.

We started out with just an API executor plugin based on Lama2(L2) syntax, now it can take any unstructured or less documented web projects and deliver organized OpenAPI references and L2-based interactive API documentations. This has a huge positive impact on the developers and the customers who require the docs.

In this article, we will be discussing what makes a API documentation stand out, how to improve it, and how to generate useful analytics out of it.

Metrics to look for in API documentation: Time to First Call (TTFC)

TTFC measures how quickly developers can make their first successful API call after reading the API documentation.

A small TTFC score indicates clearer, more accessible docs and a faster onboarding experience. Tracking this metric isn’t quite that simple.

So what is a healthy target TTFC? On a scale of 5, concerning time, we can give the following scores.

• 5/5 – < 30 mins
• 4/5 – 30 mins to an hour
• 3/5 – 1-2 hours
• 2/5 – 2-4 hours
• 1/5 – 4+ hours

These are the steps a user will take on encountering a new API. Improvements in each stage will help to reduce TTFC:

1. Browse

A developer browses your website and documentation to figure out what your API offers judgments are formed at this very early stage, likely while comparing your product among alternatives. A better marketing message is as important as providing better API documentation for a good TTFC. For example, if your documentation and onboarding process appear comparatively unorganized and filled with errors, it reflects your bad tech.

2. Signup

Signing up for an account is a developer’s first commitment. It signals their intent to do something with your API. Frequently going hand-in-hand with the next step, signing up is required to generate an API key.

3. First API call

Making the first API call is the first payoff a developer receives and is often when developers begin more deeply understanding how the API fits into their use case. Stripe and Algolia embed interactive guides within their developer documentation to enable first API calls. This is where the interactive LiveAPI widget comes into play. It helps to get them one step closer to implementation.

4. Implementation

Once a developer understands how the API functions, they apply it to their applications and accommodate their specific use cases, don't hide the tricky parts in this stage, as you may be shifting the friction to the implementation stage. Productivity shortcuts like SDKs, libraries, and code generation can help ease this transition.

LiveAPI has in-build code conversions which are tested to work fine in many languages. It helps you with the implementation making it 10x faster.

5. Usage

Once an API is implemented into production code, a developer decides whether to deepen the adoption of your API. They might increase traffic or accommodate other user scenarios. This is when developers take a hard look at latency, responsiveness, flexibility, and scalability.

At every stage of this journey, developers learn a little more about your API — what it offers, how it can be implemented, and why they should use it over other solutions. A developer’s first API call is the first payoff in the journey that simultaneously shows a developer the what, how, and why.

How to Measure TTFC

You can measure TTFC subjectively with usability testing and user feedback. You can measure TTFC objectively with web analytics to calculate the time difference between some point of discovery (like a website visit, sign-up, or another first contact) and the developer’s first API call.

To get more information on how users interacted with our API docs we need an analytics tracking platform. Next, we will try to set up Microsoft Clarity to get analytics out of the Lama2 API documentation.

Understanding User Interactions within Your Documentation

We needed a mechanism to know how people interacted with the API document and what the customers found more useful. It would also help us design more customer-centric features.

There are many Analytics providers in the market. We chose Microsoft Clarity for analytics because it can store user interactions as videos.

To set up Clarity we need to add a script into the head tag of every document we want to monitor. There are many integrations possible. We will be using the script instead.

Microsoft Clarity Integration With Mkdocs

We are using mkdocs for the Lama2 Examples page. Lama2 is a markdown-inspired API client. We have an API documentation page for that to explain the L2 syntax. Integrating clarity into the documentation page is quite tricky. Mkdocs use markdown files to create pages for documentation.

The challenge is to add the script inside the head of every HTML page. To fix this I created an overrides folder in the same directory where the mkdocs.yml is present.

Overriding the Mkdocs HTML

Mkdocs.yml file acts as a configuration file for your docs. You can specify the themes, URL, navbar, external plugins, etc.

In the overrides folder create a main.html and add a template you need to override in the docs site html.

This is the template I made for overriding the head section.

{% extends "base.html" %} {% block site_meta %} {{ super() }}

<script src="analytics.js"></script>

{% endblock %}

The analyics.js contains the connection code for Clarity. This is its contents:

(function(c,l,a,r,i,t,y){
        c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
        t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
        y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
    })(window, document, "clarity", "script", <unique_id>);

If you need anything inside the body element you can use the yml property of extra_javascript inside the mkdocs.yml file.

Here are all the features that Clarity provides.

Screen Recordings of The User Interactions

The main feature is the screen recordings. It records the user interactions like mouse clicks and page scrolls. It does not record every session but gives a decent amount of a few useful recordings. It does not store short session recordings.

We can see people who are live on the website and their interaction within the website. We can see their locations devices browser type and much useful information.

Insightful Dashboard

We have a standard dashboard with useful insights like unique users to the site, types of clicks, referrers, browsers, devices, and much more. Other useful data is the average time spent by a user on your site.
There are performance meashuremens like LCP(Largest Contentful Paint), FIDS(First Input Delay), CLS(Cumulative Layout Shift), etc

Heatmaps

Heatmaps are another good feature they have. It shows the most visited and interacted areas on a page. Your badge usually will have a call-to-action piece, like a sales button. The heatmap should show good results in that area. Otherwise, there is something wrong with your User interface.

Here are some design tweaks that will help you with reach out better with your API documents.

Design Tweaks that Can Enhance Your Documents

Add Dark mode

Have a dark mode icon on the docs page. Programmers prefer dark mode over bright mode.

Rate This Page Feature

Rate the page feature will help you better connect with the developers and gain feedback on what to improve.

Instant Load

This is the era of the internet and your page needs to load instantly. Taking a long time shows incompetency and technological decrementation.

Status widget

Show the status of the docs, like if the servers are active, live, or down. This will give a proper indication to the users.

Click to Copy

Add a click to copy wherever you are providing code snippets and results of API requests. This improves the accessibility of your API documentation.

TOCs

Add TOC(Table of Contents) in the lift panel. People generally give more attention to the left side of the screen. Hence it will help people to easily scan your page and navigate faster.

Conclusion

I hope this article helped you understand basic things to keep in mind while designing API docs. If you need any assistance regarding building API documentation you can reach out to us. We also offer professional API documentation services at an affordable one-time rate. Thank you for the read.

FeedZap: Read 2X Books This Year

FeedZap helps you consume your books through a healthy, snackable feed, so that you can read more with less time, effort and energy.