Company

Introducing: Our New API Docs

byon September 16, 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:

Scale AI's Original 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:


  1. Unify the API reference and the Customer Dashboard documentation into a
  2. unified website.

  3. Improve the developer experience. Instead of only showing static code
  4. examples, ReadMe enables developers to submit API requests directly with
  5. their Scale API key. ReadMe also has built in search functionality to make
  6. it easier for developers to find specific topics.

  7. Democratize the content creation process. Instead of editing raw markdown,
  8. making a pull request, and then deploying to a server, we just had to
  9. update the text we needed in the ReadMe UI. Ultimately, the ReadMe
  10. 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.


Latest State of API Documentation



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.


Scale 101: Key Concepts



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.


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.


Search Functionality


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.


Light Mode/Dark Mode


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.


The future of your industry starts here.