This guest post comes from Peter Gruenbaum, founder of SDK Bridge. He has worked as an API writer to explain technologies as diverse as telecommunications, mobile apps, high-tech tractors, and funny pictures of cats.
There’s a lot that’s been written about the content of API documentation, but what about its look-and-feel? Unlike many types of information, API documentation is not meant to be read front-to-back, but is meant to be scanned for relevant information. This means that the look-and-feel should be very clean. Clarity is a much higher priority than aesthetics.
As a result, there’s a simple Golden Rule when it comes to color: use black and white. But there are some exceptions, and this article will describe how and why to use them.
Black and white provides the most contrast. It provides no distraction between the reader and the content. Don’t worry about it being boring or not matching your branding. The main goal of API documentation is to communicate what are often complex concepts, and your look-and-feel needs to get out of the way of the information in order to make that happen.
If you want to add some color to help break up the page, typically you’ll want to stick to blue and gray. These colors are less likely to detract from the black-and-white content. Examples of where you might use these color highlights include headings, code samples, and tables.
Example: LinkedIn API page.
Use color to indicate to the reader that some text acts as a link. Classic blue is always a good idea here. Links will be spread liberally in API documentation, and you want them to be noticeable, but not distracting.
Example: Twitter API page.
If you have short paragraphs that especially require the readers’ attention, such as notes and warnings, it can be useful to use special colors that stand out. Choose a color that’s not blue or gray, but don’t have it be too strong, or it will draw too much attention.
If you are documenting a REST API, you can use colors to distinguish between the different HTTP method types: GET, POST, PUT, and DELETE. Some automated systems (such asSwagger) create this color coding automatically. Swagger’s color scheme may be a little too bright; a more mellow set of colors would distribute the readers’ attention on all of the information and not just pull it to the method type.
Example: Swagger demo API page.
If you are documenting an SDK, you may want to indicate addition information, such as whether a class member is public, protected, static, etc. You can use small icons to indicate this information. The icons should be small enough not to visually distract from the text, and should provide information when hovered over.
Example: .NET documentation on MSDN.
Be very careful using color for branding. It can easily become a visual distraction. However, if you use it sparingly, it can be quite effective. Twilio is a good example of using their brand of red for headers. Note that all other colors are black, white, or shades of gray.
Example: Twilio API documentation.
These rules, exceptions, and examples should help guide you when designing the look-and-feel of your API documentation. Remember that the guiding principle is clarity, and that color should be used to inform and not distract.