Most engineering oriented organizations encounter a moment when documentation starts to feel lacking. Products evolve rapidly, but documentation often lags behind. Eventually someone on the team says what everyone has been thinking: “Honestly… our docs feel a bit shit right now.”

Notifly was no exception. Notifly is a unified messaging automation CRM solution trusted by over 100 customers, helping growing teams manage customer communication seamlessly across every channel.

They were operating on a Docusaurus-based developer documentation system, with most content built as static MDX pages. As their product expanded, this structure started to make them exhausting—both for introducing new features and for guiding partner developers. The team wanted documentation that was clearer, more intuitive, and more aligned with the developer experience they envisioned.

When we first sat down with the Notifly team, the most important message we shared was this:

documentation quality is not determined by whether you use zylo-docs or any other document deployment platform—it’s determined by structure and clarity.

A platform change alone doesn’t create readable documentation. Once the structure is sound, any great platform can shine. That’s why instead of pushing our own platform, we recommended Mintlify—a system with strong component support and great UI flexibility. Of course, they've tried Mintlify before.

First, we rewrote endpoint titles and descriptions in natural Korean because Notifly’s documentation is primarily consumed by Korean developers, grouped APIs by topic rather than internal function names, and reorganized content into a structure that flows intuitively. This wasn’t just translation—it was a fundamental rewrite tailored to how developers actually read and learn.

One developer told us during an interview:
“I finally understood how this service works after actually integrating the API.”
That was exactly the kind of experience we wanted to fix.

Rebuilding the Entire API Layer with OpenAPI

The core of our work was a complete migration of Notifly’s API documentation into a single OpenAPI spec. Managing APIs through scattered MDX files leads to inconsistencies over time, makes maintenance difficult, and prevents automation.

So we rebuilt everything.

• Replaced 10+ MDX files
• Consolidated all request/response schemas
• Unified error and security schemas under shared components
• Produced one clean, maintainable OpenAPI file (~2,800 lines)

This structure not only reduced duplication, but also made future iteration and management much faster.

Unlocking Mintlify’s Power with x-mint Extensions

Migrating to OpenAPI opened the door to using Mintlify’s advanced UI features.

To make the most of the platform, we heavily used the x-mint extension system.

This allowed us to:

• Configure custom titles and descriptions
• Inject Open Graph metadata
• Organize endpoints cleanly
• Add richer examples linked directly from the spec

We also connected the spec to Mintlify’s docs.json(configuration file) to support advanced theming and component integration. Because examples live directly in OpenAPI, Mintlify’s Playground where users can test and explore API endpoints automatically displays sample requests and responses.

Not every complex schema renders well in the Playground, but we addressed this by highlighting essential flows visually and using Mintlify’s <Callout> components to guide readers through more complex structures.

A Completely New Documentation Flow

Notifly initially expected only a migration and partial improvement. Instead, they experienced a complete reinvention of their documentation flow by working with zylosystems.

We reorganized the docs into a natural narrative:

1. Getting Started
2. Authentication
3. Core API
4. Usage Examples
5. Error Handling

This replaced the previous fragmented, function-based structure and made the product’s logic clear from the beginning.

One of the most celebrated improvements was the new navigation structure. Previously scattered content became neatly grouped into coherent categories. Team members immediately noticed how easy it was to understand the entire product at a glance. We also integrated Mintlify components the Notifly team had never been able to use effectively—significantly improving expressiveness and readability.

The Result: A Documentation Experience People Want to Share

Notifly originally planned a generous timeline for the documentation overhaul. But once they saw the results, they wanted to publish it even faster than scheduled. The updated docs are now fully live in production, and feedback has been overwhelmingly positive:

• Developers understand the service much faster
• The entire document flows logically and intuitively
• Complex processes are visually clear
• The documentation finally matches the quality of the actual product

Readable Documentation Is the Real UX

When documentation feels lacking, it’s rarely because teams are incapable. It’s usually because they don’t have dedicated structure, narrative design, or DX expertise. At Zylosystems, we don’t simply “beautify” docs. We architect documentation that reads well, scales, and actually helps developers succeed. This collaboration with Notifly, our very first customer, is meaningful not only because it was our first—but because it proved the value we want to continue delivering.

If you’re facing similar challenges and want documentation that truly elevates your product, feel free to reach out.

nick@zylosystems.com