A new pattern for API documentation

HMRC Developer Hub is a platform where HMRC API developers publish APIs in order for 3rd party developers to consume them while building their accountancy software.

API documentation is a deliverable of technical writing, containing instructions for developers about how to effectively use and integrate with an API.

The problem.

An important program – Making Tax Digital – was blocked from releasing a new API due to the current documentation design being unfit for its purpose. The new API documentation requirements were more complex than previous APIs, including more endpoints, HTTP verbs, and documentation for multiple versions.

Initial API structure

The current documentation did not support this in a scalable readable way that was easy for developers to consume. It involved scrolling through pages and pages of documentation to find a particular scenario’s information, all in a non-hierarchical structured layout. The complexities of the new API meant we had to find a new pattern for a catalog of documentation that supports hundreds of these types of APIs in a single location.

The new API structure mapped out

The users.

Our users were 3rd party developers coming on the HMRC Developer Hub to consume APIs in their (accountancy manly, but not only) software. We had 5 main personas, out of which 3 were developers and this problem would affect all of them.

As our users were very niched experts, it was very challenging for the UX team to understand how they consume the information and what they need without asking them point blank.

I personally did a lot of desk research on how other API documentations work and what their structure and information architecture is. Also spoke with a lot of our internal API devs to try to gauge how they consume the information of a documentation and how they use it differently over time.

To better understand how they use the documentation, I created a service map to surface the behaviour of our different personas through the service, at different stages of the development process.

The process.

After creating and validating the service map, I got a better idea of how the documentation is consumed over time and what is needed at each step, how it needs to be organised and especially, how users look and find specific bits of information.

“Navigating an API looks like a dinosaur. Up and down, in and out”

We found that our users would browse the documentation to see what APIs are available and then as they would find one, they would read the top-level documentation for it to see if it truly applies to them. Then they would drill down all the way to the granular endpoint level to understand how it’s used. Some at this point might even copy an example test payload or request for testing. They would then go to the next endpoint, do the same, etc. My colleagues were impressed by my amazing representation and from then on we referred to this behaviour as the dinosaur!

As there was a lot of content and various hierarchies, plus a need to navigate vertically deep but also horizontally shallow through the information, the interaction was crucial. We’ve gone through a few iterations, constantly validating with our internal API developers (producers) before going out to test with 3rd party developers (consumers) our interactive prototypes every 2 weeks.

We’ve had numerous workshops after each usability testing to discuss the feedback and findings. This process was extremely useful to nail down the exact user needs of this very expert user type.

The outcome and learnings.

The final API documentation and the new complex Self Assessment API went live on time after testing very well in numerous usability tests. The new pattern is scalable and adaptable for what is coming in the near future.

I have to admit, it was very challenging to work on a project where I didn’t understand the content, but it was so interesting to work so closely with developers. And not to mention, how satisfying it was when I would get it right and they’d exclaim that I somehow read their mind!