The best of API Documentation Design

Looked upon by many as “dry”, designing for words, in my opinion, is the pinnacle of design. Only the most seasoned and most passionate of designers wander into this area of design.

Need help with API documentation design? Get in touch with me.

Unlike many other types of ‘design’, Documentation design is judged a bit differently. Your design and writing must result in people spending as little time using documentation as possible (vs the likes of Facebook, where you are destined to waste time by design). In general, if there’s too much to say, it’s too complex to easily be understood.

Migo Money — API Documentation design in consideration by Yuriy Sklyar @ Threefifty

The recipe for a successful documentation website

Main navigation

• Always available (sticky).
• Short names/links, preferably single word.
• Shouldn’t take away from vertical screen real estate (shouldn’t be positioned at the top).

Secondary navigation

• Always available (sticky).
• Uses ScrollSpy to let the user know of their location on a long page.
• Concise, and by default consists only from main categories, that are auto-expanded upon scrolling.

Content

• Simple-to-understand.
• Short and to-the-point. Include ONLY what is needed. This isn’t a novel.
• Eliminate long paragraphs by breaking them up into bullet point lists or shorter paragraphs.
• Single idea per paragraph.
• Sections must be clearly visible.
• Sparingly use icons and illustration to break down the monotony of text.
• Utilize tables and special content highlighting (such as info and danger/warning messages/alerts) to create for a more engaging and useful experience.

Documentation Design vs Marketing Design

Selecting the right content architecture for your documentation is crucial for its successful adoption.

Since documentation websites heavily rely on large amounts of text, it is advised for them to follow the commonly established pattern of a “documentation/community” website rather than a marketing presentation.

Documentation template

• Logo always visible, resulting in higher brand recognition.
• Intelligent use of space = no wasted space.
• Fits more content.
• Ability to fit more links in main menu.
• Perceived as less of a ‘business’ template.

Marketing template

• Navigation takes away from valuable vertical screen real estate (if sticky).
• Logo isn’t always visible, resulting in lower brand awareness.
• Wasted space on both sides of the screen.
• Fits less content.
• Limited amount of links in main menu.
• Generally perceived as more of a marketing approach to content presentation.

Content & Design architecture

Placing your content in the center [like a king] is preferred as it eliminates unnecessary eye shift to the right/left side of the screen. Another point to keep in mind is that the content cannot span the entire width of the screen, and should be formatted into reasonably short columns (like newspapers).

Examples of “best” API documentation:

YouTube API

Cons:

• Too text-heavy.
• Paragraphs too long.
• No copy color variation.
• Too many main categories + you can further expand each one...
• Strange red line in the secondary navigation.
• Double header takes away from valuable content real estate

PayPal API

Cons:

• Text-heavy.
• Paragraphs too long.
• No copy color variation.
• Difficult to distinguish main and secondary categories.
• Top header navigation takes away from valuable content real estate.
• Too much wasted space on sides.

Facebook API

Pros:

• Less text.
• Shorter paragraphs.
• Page effectiveness collection via user vote.
• One of the best API docs in the industry.

Cons:

• Text too small.
• Text too gray (too little contrast).
• Overly monotonous in its presentation, design and structure.
• Top header uses up space.

Dropbox API

Cons:

• Not very useful.
• Too much wasted space.
• Too much separation.
• Too many clicks.
• Not enough content.

Microsoft API

Pros:

• Page effectiveness collection via user vote.

Cons:

• Main navigation too tall and overburdened.
• Category/subcategory titles wrap/are too long.
• Too wordy. WAYYY too wordy.
• System becomes complex whenever a user is permitted to expand main categories.

Stripe API

Pros:

• Page effectiveness collection via user vote.
• Clear hierarchy and categorization.
• Use of Scrollspy.

Cons:

• Main navigation too overburdened — users can get lost.
• At times things get a bit wordy.

Box API

Pros:

• Less text, shorter paragraphs.

Cons:

• Disconnected layout/architecture.
• Can’t see examples.
• Text too light/not enough contrast (do you see books with light gray letters…? Duuh!).
• Main navigation too overburdened.

Uber API

Pros:

• Less text, shorter paragraphs.
• Right-hand sub-category navigation + Scrollspy.

Cons:

• Text too small/tight.
• Main navigation too overburdened.

I’d say the winner in this list is Stripe’s or Facebook’s API Documentation…

Choosing the right documentation system

Your choice depends on two things: whether you want to make life easier for yourself, or for your users. For example, an off-the-shelf system like Slab, GitBook, Coda, Notion, Outline, ReadMe or GitLab will be easier to use/maintain, but it will provide for a limiting experience for your audience which has a potential to hinder your adoption rate.

Issues with auto-generated API documentation

The most obvious benefit of auto-generated documentation is that you don’t need to do anything. The system will take care of it all for you.

…But then again, if you put no effort into your documentation, why should your user?

When selecting something like Spectacle to automate generation of your API documentation, you’re walking a fine line between internal ease of use, and the external usability [and therefore your success of adoption].

Usability issues

• Disconnected examples.
• Awkwardly offset content.
• Narrow content field due to unnecessarily oversized example column, which is empty for the most part.

Usability issues

Too much unnecessary repetition throughout the document.
• Does Description really need a “description” title?
• Why do we make people click on something in order to find out its meaning?

Usability issues

• “Schema Descriptions” should be part of “Operations” to be more useful and to reduce clicking/scrolling.
  • No clear indication of where you are located on a very long page.

Metrics of success

Bounce Rate

It is a case where high bounce rate is welcomed as long as it is accompanied by frequent returning visits.

Session Duration

A useful and concise, self-help documentation resource could result in shorter-than-average visits. This is a testament to a well-written, informative content.

Collect user feedback

Was this page helpful? Yes/No. Improve it based on user ranking.

A/B and multi-variate testing

Test the effectiveness of design via incremental design improvements.

3rd party documentation platforms

Slab
GitBook
Coda
Notion
Outline
ReadMe
GitLab

BONUS: Lights out

As a bonus usability feature, and something majority don’t consider, is the ability to ‘dim’ the design of documentation for when you are working in a dark environment, where white version would kill your eyesight:

Migo Money — API Documentation design in consideration by Yuriy Sklyar @ Threefifty

Where to find me online:

I document quite a bit on my personal blog: www.yuriysklyar.com

Facebook|LinkedIn|Instagram|Quora|Pinterest
Behance|Vimeo|YouTube
SoundCloud|MixCloud
Tinkercad|Thingiverse|MyMiniFactory|Pinshape|Instructables|Cults 3D