
Summary
This guide is my evaluation of the FINRA API documentation. It details suggestions for improvement of the following:
I’ve separated FINRA API documentation into two categories:
- Onboarding guides in the FINRA API Developer Center.
- API reference in the documentation console.
It’s important to clarify the differences between onboarding guides and API reference documentation.
- Onboarding guides (or tutorials) help users learn about the FINRA platform and products. Often they include example use cases. Onboarding guides must be separated from the API reference documentation.
- API reference documentation is designed for developers in need of quick reference materials. They understand how to onboard themselves and interact with the FINRA endpoints. Thus, API reference content is simple. We can link out from API reference documentation to the onboarding guides where appropriate.
FINRA API Developer Center
Get Started
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.
Onboarding Guides
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:
FINRA Products
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:
Writing Style Guide
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.
API Reference Documentation
Getting Started
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.
Nested Topics
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.
Backstage
User Analytics
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.