Highlight
What if we could make it much easier to view and edit your documentation?
👆 Mintlify's current editor
After setting up my repo, adding some pages, and testing all features, I got an excellent understanding of how everything works. That said, I had issues with some parts of the editor. Namely—
Navigation
Markdown formatting
I’d go into details presenting possible solutions to these.
It can be confusing therefore requiring extra learning to get through to how it works.
It is hard to visualize how the navigation will look in the documentation before publishing it live.
Solutions will be presented through the eyes of Lily, a software developer.
I implemented a visual navigation system using a pattern Lily is used to. Each folder is presented visually to Lily—the breadcrumbs pattern on the navbar and the visual representation of files on the sidebar. This makes it easy for her to navigate to any part of the documentation.
From the sidebar, she also sees the nesting level of each folder.
How does what I am doing look like?
In certain places, Lily can preview how the changes would look on the live site. This is to make the experience as seamless as possible.
Lily can preview how her sidebar will look like.
When she navigates to the tab section, Lily can see how the tabs will show up on the documentation website.
Distinct Icons
Icons for various sections are distinct. This is so Lily can easily differentiate between them. Tabs, Groups, and Files respectively.
Adding content
Not currently in the editor. Lily can add files and groups directly from the editor. Creating a group inside another is similar to nesting it.
Ok…what now happens to the Mint.json file?
Although not within the scope of this case study, Lily still has full access to the Mint.json file. She can choose to make her edits there. You can liken the above to a visual representation of the mint.json navigation section.
For lengthy documentation pages, it is easy to get lost in the code. Currently, you can’t move the preview to the current section of the selected code.
This assumes every developer or technical writer has a good understanding of ‘.mdx’ files.
I believe there should be a better way. One where Lily can switch between editing her page in Markdown or via a Canvas. Which brings me to…
A simple analogy to pass the idea—Notion but this time for documentation.
Here’s what I mean. Lily is given a canvas where she can add content called blocks. Blocks could be Text, Headings, Info, Tip, Accordions etc. To access these blocks, she uses the ‘ / ’ command. This opens a menu for her to choose what blocks to add.
What can be added?
Every block can be added and edited. Here are a few of those blocks.
Heading
Lily can directly add headings on the canvas
Info
Lily can directly add and edit info on the canvas
Accordion
Adding an Accordion is done the same way. Lily enters the title, clicks the dropdown, and enters the description.
Codeblock
Lily can choose the name, change the language, and edit the content of her code block
Card
Lily can also add a card from the command menu. Hovering on the card [and other blocks] gives you 3 options. Edit the content, move, or delete the block. Lily can edit the card to change the Icon and URL.
ResponseField
Lily can add and edit the contents of a ResponseField. She can also nest other blocks within. Here, she is nesting an Expandable within the ResponseField.
Text-editing
Lily can turn texts into Code, Italic, Bold, Underline, Strikethrough, Subscript, and Superscript.
Others?
To keep this case study concise, it will be impossible to include every single command. The goal was to present an opportunity to improve the experience of the editor.
What if Lily likes her Markdown?
She can always view and edit the content of the page by revealing the Markdown format which is hidden by default.
Figma file…
Check out the Components, Moodboards, and structure
Conclusion…
As I mentioned above, this is not a holistic solution to all of the editor's problems. A lot of features were left out to make this case study as concise as possible.
Thanks for viewing!