Stripe’s new API reference documentation
Stripe’s original API reference is widely credited with popularizing the three column layout for API reference documentation. The first column contained the navigation while the second and third contained the descriptions and code samples respectively. The advantage was that you could look at the sample code and view the meta data in one view as shown below.
It was also an eye catching and beautiful design that was quickly imitated by others. The entire API reference was in a single page which meant that developers could use browser search to quickly find the relevant sections. There were also a few delightful little touches, my favorite is the non select-able ‘$’ to ensure that it is not accidentally copied.
When I was worked to redesign the v2 Freshdesk API documentation, this layout was one of the contenders. However there were some drawbacks as well. The excess amount of empty space was a big concern. Unless the content in the second and third columns were of the same length, there was empty space. Many others felt the same way as well — Three column layout is a massive waste of space .
Another shortcoming in Stripe’s API reference was that there was no easy way for a developer to copy the command and run it from their command terminal. The developer would need to copy the manually select the sample command and then copy it before being able to test the API.
The redesigned documentation
A couple of weeks ago I happened upon the new API documentation and I was impressed with how they have managed to solve almost all the issues that I saw while still retaining the famous Stripe three column layout.
All it took was one clever little change - since most of the time the third column was the one with empty space, the code samples are now displayed in cards that stay locked in place while you scroll through the description. This simple change eliminates the empty space issue almost entirely.
There is also a new night mode that can be activated using a toggle that rather delightfully switches between a symbol of the sun or moon. Click to copy has been added as well. Another feature I really like — by default the sections in column 2 are compressed, you can expand them if interested. This makes skimming through the docs really easy.
The search capability has been enhanced by taking over the default Ctrl+F browser search and displaying a search modal instead. You can choose to dismiss this and use the regular browser search, but the advantage is that it searches the entire Stripe documentation (guides, tutorials etc) as seen below.
The only new issue that I saw is that by moving the third column code snippets into cards, the available width has shrunk. Since many lines in the sample code would not fit, they have chosen to add horizontal scroll bars rather than break the formatting. This may prove inconvenient to those who want to quickly scan through the code and JSON samples.
Overall, it’s a beautiful design that improves handily upon the original and once again, sets the standard for API reference documentation design.
