Enhancing the experience of a documentation platform.
This is a self-initiated redesign. I don’t work at Mintlify, and no one commissioned this.
Mintlify is a documentation platform. It lets teams build and maintain fast, good-looking docs sites, and folds AI, analytics and Markdown into the development process so writing them stops being separate.
What if we made your documentation far easier to view and edit?
After setting up my repo, adding some pages and testing all its features, I understood how it all worked. But two parts of the editor gave me trouble:
I’ll take each in turn and propose a solution.
Can we reduce the abstraction and learning curve?
From here on, I’ll show the solutions through Lily, a software developer.
I built the navigation out of a pattern Lily already knows: breadcrumbs in the navbar, and the file tree in the sidebar. Every folder is on screen, so she can jump to any part of the documentation.
The sidebar also shows how deeply each folder is nested.
In a few places, Lily can preview how a change will look on the live site before she commits to it.
Lily can preview what her sidebar will look like.
In the tab section, she sees how the tabs will appear on the published site.
Each kind of section gets its own icon, so Lily can tell them apart at a glance: Tabs, Groups and Files.
Not currently possible in the editor. Here, Lily adds files and groups without leaving the canvas, and dropping one group inside another nests it.
mint.json file?It’s out of scope for this case study, but Lily keeps full access to the
mint.json file and can still edit it directly. Everything above is a visual
layer over its navigation section.
Mintlify prefers Markdown for writing documentation. That’s great, but it brings a couple of problems:
.mdx well.There should be a better way: one where Lily can switch between editing in Markdown and editing on a canvas. Which brings me to…
The short version: Notion, but for documentation.
Here’s what I mean. Lily gets a canvas she fills with blocks: text, headings,
info, tips, accordions. Typing / opens a menu of everything she can add.
Lily can add and edit every block on the canvas. Here are a few of them.
Accordions work the same way: Lily types the title, opens the dropdown, and fills in the description.
Lily names the block, picks the language, and edits the code.
Cards come from the same menu. Hovering over one, or over any block, reveals three controls: edit, move and delete. Editing a card sets its icon and URL.
Lily fills in a ResponseField, and can nest other blocks inside it. Here she nests an Expandable.
Lily can set any run of text as code, italic, bold, underline, strikethrough, subscript or superscript.
To keep this case study concise, I won’t include every single command. The point was to show where the editor’s experience could improve.
View the components, the moodboards, and the structure.
As I said, this isn’t a complete solution to the editor’s problems. I left a lot of features out to keep the case study tight.
Thanks for reading!