How We Built Our Developer Docs With Mintlify & Fern

If you run a dev tools company, you know how important documentation is. In fact, you could argue that it’s more important than your website. So in May we decided to overhaul our docs to help us create richer content for developers. The goal was for every software engineer arriving at the docs site to quickly understand what Trophy does and how to use it.

This is a brief outline of the decisions we made and why we made them, but if you just want to check them out for yourself head over to docs.trophy.so.

Picking a Docs Provider

The documentation-as-a-service space seems to be gaining a lot of momentum. It seems like in the past few years there are more ways than ever to create and host a docs site.

We looked into a few different providers including GitBook, Docusaurus, Hashnode, Fern and Mintlify. There were various factors in the decision but the TLDR is that while we manage our SDKs with Fern, we chose Mintlify for docs as it had the best writing experience, supported custom React components, and was more affordable for hosting on a custom domain. Both Fern and Mintlify pull from the same single source of truth for the SDKs and docs site, respectively: Trophy’s OpenAPI spec.

If you’re building API or SDK docs, we strongly recommend sticking to OpenAPI rather than platform-specific specs like the Fern definition. This is because basically every docs-as-a-service provider supports the OpenAPI spec, so if you use it, it’s trivial to swap providers if you’re unsatisfied with your current one or a new one enters the market with a more compelling offering. We took advantage of this optionality when migrating our API docs from Fern to Mintlify.

Deciding on the Best Navigation

When choosing a navigational strategy for our docs, we had the following things in mind:

• Surfacing the most important concepts in as few clicks as possible.
• Making important resources like our GitHub repositories and status page easily accessible.
• Clearly segmenting our platform docs, API reference, tutorials, and examples.
• Making it easy for developers to get help when needed.

We tried a number of approaches but eventually decided on a tabbed layout.

• The Home tab is the default tab and is designed to answer the ‘whats’ and ‘whys’ about Trophy in terms of its features and why developers should use them.
• The Guides tab is built to answer the ‘hows’. Once you’ve decided what you want to build, then this tab gives developers practical examples and shows best practices for implementation.
• The API Reference tab is a playground for developers to explore all the functions Trophy has to offer. It’s great for testing out ideas before jumping for the keyboard, or for finding specific details about a particular endpoint not covered in the rest of the docs.

Featured in every tab are some key links to important resources like our GitHub, for learning more about our SDK’s, and our status page. There’s also a quick ‘mailto’ link to reach support if required as well a support section at the end of every page in the docs.

Creating Richer Content

Flowchart Diagrams

A picture paints a thousand words and that’s true for documentation as well. In areas where we think it’s particularly important that core concepts are conveyed clearly, we’ve added Mermaid diagrams to help get the point across.

Code Snippets

No docs site would be complete without code snippets, but we’ve made it super easy to get the most relevant snippets for your stack by including snippets in each programming language that we support.

A lot of snippets also helpfully highlight the relevant parts of the code that are being discussed in the prose:

Getting Feedback

Part of the overhaul was building in ways for developers to tell us what they think about each page, and to suggest improvements or additions. As our docs are open source, it’s super easy for anyone to either suggest edits or raise issues directly in GitHub.

Our Docs Roadmap

There’s still a lot of work to be done to make our docs even better for developers like:

• Making each page user-aware. If developers are already logged into their Trophy account then we’d love to show them code snippets and examples with API keys and preferred programming languages already filled in, just like Stripe does.
• Adding support for other languages to make our docs more accessible for non-native English speakers.
• Integrating LLMs into our docs, so you can ask a question and get a relevant answer quicker than searching through yourself.

Summary

The process of updating our docs took about a week, and we’re super happy with the result. If there’s something you’d like to see or have any questions about setting up your own docs site, then feel free to reach out.