Three Types of Developers Reading Your API Documentation

Whenever I update an API documentation page, I think of three different people reading it: a junior developer, a mid/senior developer with no prior experience in the field, and someone who has used a similar tool before.

All of these people require help with the same tool, but none of them require the same content. The ideal documentation explains the same thing multiple times, but each description is slightly different.

Junior Developer

The ease of creating a guide for a junior developer is a paradox. On the one hand, you're working with almost a blank canvas and the person doesn't have any preconceptions. You can use the terminology that's most suitable to you and "teach" the person how stuff works from the ground up.

On the other hand, putting yourself in the shoes of a junior is extremely difficult. Coming up with what exactly should be included in the guide can be problematic.

One of the main questions you need to answer is how much hand-holding should you do. Is it enough to only write a "Getting Started" guide to your service or should you go even more basic and teach how to set up a development environment or a server.

Understanding how deeply you should go with your documentation comes from understanding who are you targeting and how complicated is the product.

The most obvious content type for beginners is a detailed step-by-step guide. Keep it short and simple. Don't skip on information that's required to run the examples and try to get to a positive result fast.

An important block is to explain what to expect. Display the API response, explain HTTP codes and potential API error responses. An experienced dev might catch the custom HTTP headers in the response, but a junior needs a bit more hand-holding.

Display the complete code. If your tool allows minifying more irrelevant parts then do that, but display all the code. Don't expect a dev to put the parts together from different pages to run the application. Examples should be self-sufficient.

Mid/Senior developer without prior experience

Any experienced developer will enjoy a well-crafted getting started guide. But there's a high chance that they'll go over them quickly and then move on to more specific details like API reference, topical guides, and specific features.

For the more experienced devs, but without experience in the field, it's good to focus on the technical aspects of the tool. Code examples are very valuable, but it's likely the dev will want to know how the tool works, and that’s why having a dev portal comes in handy.

Remember, the person doesn't know the field so give him a quick technical overview of how stuff works. In Messente, for example, we use our partners to deliver messages to the actual devices. Explain this flow to the customer, so they can expect certain behaviour.

Topical guides, case studies, and specific examples become more valuable with this type of developer. There's less need to explain how to install the API library and more focus should go into the feature specifications. In this scenario, hiding code in the examples may be fine if it highlights the point more clearly.

Developer with experience in the field

Someone who has used, for example, an SMS API before is probably not going to need a lot of hand-holding to implement Messente.

It's important to show examples of how the API works, but most of the effort should go into specific details.

One of the key topics to describe is how the service differs from others. People with prior experience expect things to work in a certain way and if it doesn't then it creates confusion. The aim of the documentation is to highlight the peculiarities with your product that might not be so common in others.

Have an API reference that's easy to follow. The developer already knows how most things work so it's a matter of figuring out how the properties are named, what are the features and limitations.

People familiar with the product is also a great segment to promote any supportive tools. If you have APIs that don't exactly provide the core value but are supporting your tool (e.g. Pricing API, Statistics API) then it's a good idea to bring this out. People with experience are probably not overwhelmed by the tool itself and know how to appreciate helpful add-ons.

Summary

There isn't a clear cut in what type of documentation a junior or an experienced developer should have. A junior might appreciate a good API reference and a senior is likely to be quite happy with a nice getting started guide. However, it’s still important to focus on those three developer types and personalise your API documentation accordingly.