Facundo Pepe

Back on September 16th, we introduced you to our <a href="https://scale.com/blog/introducing-our-new-api-docs" rel="noopener noreferrer" target="_blank">new API Docs</a>. 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 <a href="https://github.com/scaleapi/custom-documentation-example" rel="noopener noreferrer" target="_blank">in this repository</a>.<h2>Some Context:</h2> 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.<h2>Why Tailwind?</h2> 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.<h2>Why Next.js?</h2> Next.js is one of the best React Frameworks out today. Since the launch of <a href="https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support" rel="noopener noreferrer" target="_blank">SGG support</a> in March, it’s a no brainer for a fast and performant website and API docs. Quoting them from their own <a href="https://nextjs.org/blog/next-9-3#next-gen-static-site-generation-ssg-support" rel="noopener noreferrer" target="_blank">blog post</a>:<img src="https://imagedelivery.net/wLbZE4_NzVVdgHc15St55g/4a743efa-0436-43a8-18b6-9368be8e8a00/public" alt="Next.js Quote"> 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 <a href="https://nextjs.org/docs/api-routes/introduction" rel="noopener noreferrer" target="_blank">here</a>. <h2>Why Readme?</h2> As we highlighted in our previous <a href="https://scale.com/blog/introducing-our-new-api-docs" rel="noopener noreferrer" target="_blank">blog post</a>, we chose ReadMe as the platform for our API documentation because ReadMe allowed us to: <ol><li> </li><li> Unify the API reference and the Customer Dashboard documentation into a</li><li> unified website.</li><li> </li><li> </li><li> Improve the developer experience. Instead of only showing static code</li><li> examples, ReadMe enables developers to submit API requests directly with</li><li> their Scale API key. ReadMe also has built in search functionality to make</li><li> it easier for developers to find specific topics.</li><li> </li><li> </li><li> Democratize the content creation process. Instead of editing raw markdown,</li><li> making a pull request, and then deploying to a server, we just had to</li><li> update the text we needed in the ReadMe UI. Ultimately, the ReadMe</li><li> platform provided a richer and more dynamic user experience.</li><li> </li></ol><h2> </h2><h2> Sharing our example code with the developer community</h2><h2> </h2> 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 <a href="https://github.com/scaleapi/custom-documentation-example" rel="noopener noreferrer" target="_blank">Github repo</a>. We hope this sample code allows you to build your own beautiful and customized documentation.

How to customize your API Documentation’s front-end leveraging cutting-edge platforms and frameworks.

Facundo Pepe

Quick Start Guide to Customized API Documentation