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

in this repository.

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

SGG support

in March, it’s a no brainer for a fast and performant website and API docs.

Quoting them from their own

blog post:

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

blog post,

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
Unify the API reference and the Customer Dashboard documentation into a
unified website.
examples, ReadMe enables developers to submit API requests directly with
their Scale API key. ReadMe also has built in search functionality to make
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.
platform provided a richer and more dynamic user experience.
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

Github repo.

We hope this sample code allows you to build your own beautiful and

customized documentation.