Quick Start Guide to Customized API Documentation
Back on September 16th, we introduced you to our
new API Docs. Today, we’re pleased to follow up the original announcement with further
details on how we implemented this with Next.JS, Tailwind CSS, and ReadMe.
Furthermore, rather than simply describing how we used each platform and
framework, we have packaged together an example for you to implement and build
off of
Some Context:
At Scale AI, we are building the critical tools that make it easier to build
and scale real-world AI systems. To provide our customers with the best
experience possible on the Scale AI platform, we believe that a clear, simple,
and memorable front-end, user interface, and user experience is critical.
Scale’s design team has been hard at work building out a design system and
improving customer-facing interfaces to bring front-end consistency across our
platform.
Most important to this effort was to implement the design system across our
different applications. We decided to use Tailwind CSS as a CSS framework and
CSS Modules as a way to add custom elements when some customization was
needed. To ensure our website and applications were highly performant and
loaded quickly, we chose to use Next.js as our react framework.
Why Tailwind?
Scale’s design team have used Next.js and styled-jsx as a way of providing CSS
styling since the initial launch of our website. While this was fine when
there were fewer pages on the website, it proved to be hard to scale and
maintain a design system without proper documentation. At this point the team
faced two options: we could either spend a lot of time creating and improving
our own CSS and writing documentation for it, or we could use a CSS framework
that could adapt to our needs.
Since the Scale team prefers not to re-invent the wheel when it isn’t needed,
we decided that using a CSS framework would yield the best results in the
shortest period of time. Tailwind has allowed us to expedite the development
of new layouts and pages while maintaining consistency across our website.
Tailwind also has the advantage of having strong documentation behind it to
support future development. Using Tailwind has also freed the team up to spend
more time focusing on special details for each page like custom animations and
interactions.
Why Next.js?
Next.js is one of the best React Frameworks out today. Since the launch of
in March, it’s a no brainer for a fast and performant website and API docs.
Quoting them from their own
Next.js’s API routes also proved to be helpful as we used this to retrieve
the search values made by the user. More on their API Routes
here.
Why Readme?
As we highlighted in our previous
we chose ReadMe as the platform for our API documentation because ReadMe
allowed us to:
- Unify the API reference and the Customer Dashboard documentation into a
- unified website.
- Improve the developer experience. Instead of only showing static code
- examples, ReadMe enables developers to submit API requests directly with
- their Scale API key. ReadMe also has built in search functionality to make
- it easier for developers to find specific topics.
- Democratize the content creation process. Instead of editing raw markdown,
- making a pull request, and then deploying to a server, we just had to
- update the text we needed in the ReadMe UI. Ultimately, the ReadMe
- platform provided a richer and more dynamic user experience.
Sharing our example code with the developer community
We developed the new API documentation during Scale’s Hackathon. We are
incredibly proud of what we accomplished in just one week and we wanted to
share our solution with anyone who is looking to solve a similar problem.
Rather than simply providing a step-by-step instruction for this solution,
we have packaged together an example for you in our
We hope this sample code allows you to build your own beautiful and
customized documentation.
