Company
Introducing: Our New API Docs
by Scale Team on September 16th, 2020
At Scale AI, we envision a future where AI is as easy to build as any software. To help AI achieve its full potential, we are building the tools that make it easier to build and scale real-world AI systems. We began by focusing on the data - the foundation of all AI applications. With the Scale AI platform, customers can understand, visualize, and curate raw datasets, send raw data to be annotated, then debug model performance - all in one place.
From the beginning, we knew the Scale AI platform had to be API-based to enable teams working on AI and ML to automate their data pipelines and seamlessly integrate Scale into ML development cycles. Since our start in 2016, our engineering team has built incredible products to deliver large volumes of training data at high-quality, whether the data input is 3D sensor data, video, image, document, or text. Despite the continued evolution of our products and the robustness of our APIs, until recently, the API documentation itself was static, with limited interactions and not a lot of details to fully understand our products, set up effective workflows, and optimize for quality.
The Evolution of our Documentation:
If you are a long-time Scale customer, you are probably familiar with this as our API documentation:
The early documentation simply served as an API reference guide. The parameters were well spaced out, included relevant examples, and showed some example code using our SDKs.
As we expanded the documentation to include content on key concepts, the customer dashboard, and other elements of the Scale AI platform, the documentation became increasingly clunky and awkward to navigate. The early documentation was also very static, with limited interactions, no search capability, and overall proved to be a less than ideal user experience.
Transition to ReadMe
Earlier this year, our Customer Experience and Field Engineering team identified ReadMe as an industry-leading documentation platform that could scale with our evolving needs.
With ReadMe, we were able to realize three tangible benefits:
- 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.
The only limitation of the ReadMe platform out-of-the-box was the lack of front-end customization to ensure visual consistency between the documentation and the rest of our website.
Latest State:
The latest update to our documentation marries the content and functionality of ReadMe with our front-end to provide a better and more consistent experience between our API documentation and the rest of our platform.
We accomplished this by effectively leveraging ReadMe as a content management system (CMS) on the back end. We then used Tailwind CSS, a utility-first framework to build the UI for the front end, and Next.JS’s static generation feature to pre-render the page into HTML on the server ahead of each request. The HTML can be globally cached by a CDN and served instantly. Technical details on how we implemented this will follow in another blog post.
New Features:
In-depth Customer Dashboard Documentation
As a Scale AI customer, the Dashboard is the central location to manage your account and your projects. The new in-depth Customer Dashboard documentation walks you through how to manage your account, your projects, get an overview of submitted and completed tasks, and audit a random sample of tasks for quality.
Scale 101 Workflow Overviews
Every institution, company, and even team has their own ways of describing the data labeling workflow. To ensure every customer is successful on the Scale AI platform, we introduce the terminology we’ve developed in this section.
Make API calls using your Scale API key directly from the Documentation
Instead of static code examples, this feature enables developers to submit live API requests directly using their Scale API key.
Search
As we continue to expand the documentation, we realize it can also become more challenging to navigate to and find details on a specific topic. To offer a faster and easier way to find keywords or key phrases, we have added a new search feature in our documentation powered by Algolia.
Dark Mode
Dark mode reduces the light emitted by device screens while maintaining the minimum color contrast ratios required for optimal readability. To view the API documentation in dark mode, select “Dark” in your computer’s display settings or “Auto” to switch from light mode to dark mode at sunset or at a specified time.
What this Means:
If you are an existing Scale customer, rest assured that the updates to the documentation do not impact any existing projects, batches, tasks, or workflows. If anything, we hope these updates will clarify the expected behavior, showcase our API’s flexibility, and enable easier task creation with more effective instructions to improve the overall quality of returned tasks.
If you are just getting to know our products, we hope the updated documentation inspires you to come up with new project ideas.