The rationale behind keeping good API documentation is this: making it easier for developers to succeed in their API-related work. The docs function as blueprints—and like blueprints, they should contain all the necessary details for building but still be easy to understand. That’s why, when given the choice to work with either static or interactive documentation, a good chunk of developers still opts for the former.

Fans of static docs like the clean, simple, and sensible way of getting to know an API. This holds especially true for an API that follows the (oftentimes complex) Representational State Transfer Technology (REST) architectural style.

If you want static docs to go with your RESTful API, here are some guidelines for compiling them. Following these tips will help you assemble some straightforward, functional, and readable REST API documentation.

Invest in a Quality API Documentation Toolset

Hosted API documentation is a good investment to make not only for flashy and interactive docs, but simple static docs as well. It will make a big difference for you to have a proper toolset for documenting the REST API’s endpoints, parameters, requests, and other info. Plus, you’ll have the added convenience of a dedicated host for your docs—no need for the hassle of managing your own server for them. Do yourself and your fellow documenters the favor of anchoring your REST API documentation on a quality toolset.

Think of an Overall Organization Scheme for the REST API Docs

Before you start laying everything out, think of what your target developers would prefer when it comes to how you structure the docs. You have three good options:

• Docs where the API reference comes separately, like on a different website
• Docs with the API reference integrated into the material
• Decentralized docs that are patterned after specific product lines

When in doubt, think of the character profiles behind your would-be developers. Are you after the kind who’ll tinker with your API using SDKs or just the kind who need a basic understanding of the product? Consult with everyone else in the API team, and decide on which of these structures appeal to your “dream team” of outside developers.

Employ Sticky Navigation

One of the downsides of traditional static API docs is that it’s easy to get lost in them. It would be a pain for your doc’s readers to scroll up and down all the time, looking for the information that they need.

The solution to this problem is enabling sticky navigation features for your REST API docs. Nothing beats having a sidebar column on the left of the docs, with all the sections laid out. That way, readers can simply jump from section to section without needing to scroll from start to finish. It’s also quite conducive to the way developers read REST API content: by module, instead of from beginning to end.

Enable Saved Scroll State for Your Reader

What’s more frustrating than not being able to find the right info on a set of static docs? Developers have an answer for this, and it involves one of their major pet peeves: finding the info, then losing their place.

But this can be remedied with a saved scroll state feature in your docs. Your readers won’t have to worry when the page suddenly crashes or refreshes itself. The saved state will lead them back to the sample call, success response, or error response they were looking at.

Consider the Classic 3-Column API Documentation Layout

The docs may be static, but that doesn’t mean they have to be bland or one-note. In fact, the biggest mistake you could be making with your REST API docs is sticking to a boring format. Your static docs can stay crisp and clutter-free, but still have an ounce of flair to them.

Take, for example, Stripe’s three-column static API documentation. The first and leftmost column is dedicated to sticky navigation. The second and middle column contains the documentation proper. And the last and rightmost column allows for the material to be shown in a different programming language, be it JSON, Python, or C#. The format is neither complicated nor a direct shake-up of the original docs. But it’s easy on the eyes, it looks very classy, and it gives readers some freedom to understand the material in their preferred programming language.

The static approach can still yield some highly effective REST API documentation. But it’s best paired with some good tools, a good approach, and some good perspective on what your target developers want. Here’s to crafting static REST API docs that your readers can look forward to.