User interface and experience (UI/UX) are a crucial part of professional, in-depth API documentation. Documentation is the UI/UX of your API and poor consideration for your documentation could make an amazing API look lesser quality.
At ReadMe, we’ve set a design base you can work with—but you can also build something with your own custom code! A great developer experience means giving your users access what they want with minimal friction and allowing them to discover even more about your API beyond that. Taking the time to think about your content and how users interact with your documentation can take it to the next level.
Here’s how you can make your UI/UX shine 🌟:
1. Global Navigation
There are two main types of navigational UI to consider when creating documentation: global navigations on the top of your website and sidebar navigations containing a list of your pages.
Global navigations allow for the major parts of your documentation to be linked to your other products, or sign-ups and logins. Try to set the content within your navigation based on what a user might consider discoverable first, then based on a priority you set for your documentation.
2. Sidebars
Sidebar navigations allow for your content to be grouped based on your desired category, and give an overview of everything. Usually placed to the left of your written content, a sidebar lists all the pages within the documentation. It’s a good idea to include a breakdown of your pages within the sidebar, since listing every page without any categorization can take users forever to get through.
Consider setting global categories that can group the content or pages, and singular page lists under these categories. Think about the sections and why they're grouped, how to name them, and how pages are sorted, for an optimal developer experience.
3. Spacing
This is the amount of white space you are setting within your documentation between interface elements and written content. Spacing directly relates to the readability of your content. To get started, consider vertical spacing between your content, and set a standard based on set pixel rules and type scaling, if possible.
As a good baseline, create your own system of large, medium and small spacing sets to follow between elements and text. Following a uniform baseline improves the legibility to a user. We’ve set this for you in our base documentation template but you’re always able to create your own ruling.
4. Typography
Learning the basics of typography and how it translates into CSS can make or break the type treatment of your documentation. Creating a clear typographic rhythm and scaling is a great base to get started with, and gives your documentation a professional feel.
At ReadMe, we’ve set each project to have it’s own CSS type standards, setting a base you can get started with or improve upon! Establish a clear H1–H5 and body text—this is critical in creating a base system for your project, since most documentation is written in an editor or created in markdown. What aesthetic or feeling do you want your type to have? Is it bold and weighted or light and airy? It’s your choice, and you can create your own style.
To learn more about typographic rhythms and scaling, check out Rhythm in Web Typography.
5. Interactive Elements
Having content beyond written text makes your developer experience richer and easier to understand. These interactive elements may include:
- Code Samples
- Callouts
- Tables
- Images
- Embedded Content
- Custom HTML/CSS
We have a set of elements you can use with ReadMe, and you have the flexibility to add your own code and custom elements. Adding rich, interactive content and setting an information architecture standard allows you to establish a standard in your product documentation.
Sometimes having more than an API reference section can help developers get off the ground quicker. This all ties back to the amount of time in documentation a user interacts with and the understanding or readability of your content.
6. Calls To Action
Do you want to promote your product or get a user to start an action faster? Consider calls to action (CTA). These can be promotional or just links to another section of your documentation. CTAs allow users to learn more about the product, become more interested, or quickly find other pages in the documentation. CTAs can be brought into your written content as links or custom buttons.
7. A Keyword to Remember: Consistency
Keeping consistency is major in creating detailed and standout documentation. Consistency means keeping a clear visual style in your UI, creating a UX approach to pages and content so users know what to expect, grouping your information and writing, and creating clear user pathways to your global and sidebar navigations.
Thinking about the design and UI/UX within your documentation or project allows you to keep the experience developer-friendly. It’s a benefit to your overall product that users can understand your API value instantly and create something amazing with it. Setting standards early within your documentation fosters intention with what you’re creating, and presents the best version of your product.
