The GET STARTED button on the FINRA API Developer Center homepage links to the API documentation console. Once you navigate using the link, it brings you to a section titled Getting Started. Using the title ‘Getting’ Started is passive voice.

I recommend we convert all content to active voice such as ‘Get’ Started. Then confirm all UI button titles match topic titles in all documentation.

We need to create onboarding guides to support new users in the FINRA API Developer Center. At present, FINRA has nested getting started content in the API reference documentation. Doing so is okay provided it’s short and concise.

Bona fide onboarding guides help users understand the FINRA endpoints and products. They offer conceptual, tutorial-based guidance. Examples of onboarding guides I’ve written follow for the ShipEngine project I managed in 2019:

• shipengine.com/docs/rest
• shipengine.com/docs/labels/messages
• shipengine.com/docs/webhooks

The FINRA products developer.finra.org/products pages are thin. They lack conceptual instruction and user-friendly overviews of the products. For example, the developer.finra.org/products/query-api page must be updated to include use case examples of the Query API.

We need to write onboarding guides for all FINRA products to include overviews and example use cases.

Below are examples of developer resource onboarding guides I wrote for Epic Games in 2021:

• epicgames.com/docs/epic-account-services/consent-management
• epicgames.com/docs/epic-account-services/auth/auth-interface

We need to upgrade the FINRA writing styles to maintain content consistency. I’ve been using Google’s developers.google.com/style for nearly a decade. Best of all, it’s free.

The existing FINRA API reference documentation contains a large amount of developer content. The challenge I see for new users is finding relevant content in the sidebar. For example, the Getting Started category contains the following top level topics:

Terms of Service, Info for the Firm SAA, and Info for Other Organizations should be nested at the bottom of the UI rather than bundled in the Getting Started category. Often these topic types are considered resources. These types of documents don’t seem relevant for developers to get started with the FINRA APIs.

I recommend we create a category at the bottom of the sidebar titled Support. Then add children topics below it such as Terms of Service, Info for the Firm SAA, and Info for Other Organizations into the Support category. Doing so adds organizational structure to the sidebar. See an example of the TowerData API doc center I built in 2017: docs.towerdata.com/#contact-atdata.

Clarify Get Started Topics

I recommend we help new users find quick links to get started topics. This can be a mix of API reference content combined with onboarding guides.

Here’s a great example from ShipEngine: shipengine.github.io/shipengine-openapi/#section/Getting-Started. Notice how they link out to tutorials (onboarding guides) at the top.

The existing FINRA API reference documentation contains many nested topics within the main content. For example, in the API Console topic, there’s nested toggle dropdown topics such as Organization User and Individual User.

This is an easy fix by linking all topics on the sidebar as children under their related categories.

During my discussion with Alex on Monday, he mentioned FINRA is considering an upgrade by using backstage.io/docs/overview/what-is-backstage.

Making the switch to Backstage is an excellent decision. Besides their platform architecture, they offer robust user analytics integration: backstage.io/blog/2022/09/08/fyi-plugin-analytics-api/#start-collecting-data.

Being able to monitor user metrics is a best-in-class solution to understanding our user journeys and pain points interacting with the FINRA API reference documentation and onboarding guides. The benefit of tracking event-based interactions will reveal trends and gaps in the documentation.