Optimizing Content Experience

A Strategic Shift to Mintlify

Documentation is a critical element in product success, directly influencing how users interact with and understand our offerings. At , our recent transition to Mintlify addressed key challenges and significantly improved our documentation process. By focusing on continuous feedback and applying strategic principles, we implemented Mintlify at the right time, resulting in a more efficient and effective documentation system.

Initial Assessment and Approach

When I joined fabric as the head of the technical writing department, my primary focus was to build the documentation infrastructure from the ground up. my role was to build the documentation infrastructure from the ground up. My responsibilities included identifying content requirements, developing a content strategy, guiding the team in creating high-quality, user-centered content, and ensuring operational excellence by putting processes in place. Additionally, I focused on fostering cross-departmental collaboration to align our content strategy with broader organizational goals.

Although the challenges with the existing tool were evident, my initial goal was to avoid major disruptions. Readme had been in use for just a year, and instead of immediately considering a replacement, I focused on thoroughly assessing the tool’s efficiency. I dedicated time to identifying gaps that could impact our documentation process, understanding these limitations, and their effect on our team’s productivity. This approach ensured that any decisions we made were based on solid evidence and a thorough evaluation, ultimately leading to an informed and strategic shift

To better understand our team’s productivity and resource efficiency, I introduced the Scrum framework. This approach gave us valuable insights by helping us establish a skill matrix, identify skill gaps, and track the team’s progress. These insights made it clear which challenges were due to the tool and which were related to resource issues. As we critically evaluated these findings, it became evident that some of the efficiency problems were tied directly to the tool itself. With this understanding, we felt confident in making the move to Mintlify, which has since optimized our content experience and improved overall effectiveness.

Understanding the Tool's Limitations

When I set out to evaluate our documentation tools, the first step was to apply a product management lens to the process. Through conversations with engineers and a deeper dive into the reasons behind our choice of Readme, I quickly realized that the tool had been selected mainly to meet specific engineering needs—like publishing API docs—without fully considering what our technical writers required.

This discovery underscored the importance of a holistic evaluation process when selecting tools—one that balances the needs of all stakeholders. By taking the time to understand the perspectives of all stakeholders and carefully reviewing user feedback, I identified the key gaps in the tool's functionality that were impacting our documentation process. Despite the effort that had already gone into implementing Readme, it became clear that the tool wasn’t fully aligned with our broader goals. This insight was the catalyst for further exploration and discussions, ultimately leading us to reconsider our approach and explore alternatives like Mintlify.

Critical Challenges with Readme

The most significant challenges identified with Readme included the following:

• Dependency on external teams: Simple tasks, such as adding new tabs, required significant involvement from the Developer Experience (DX) team and Readme support staff, leading to operational bottlenecks. Troubleshooting often became time-consuming, as writers had to report issues to the DX team, which addressed them based on their availability. If the DX team couldn’t resolve the issue, it escalated to Readme support, which further delayed resolution due to the need to coordinate via email.
• Lack of collaborative review: Readme did not support collaborative review features, making it difficult for multiple team members to work on content simultaneously, which often led to potential inaccuracies and inconsistencies.
• Absence of preview functionality: Changes could only be viewed after merging into the staging environment, making the process time-consuming and dependent on additional resources.
• Limited customization: Customization options were restricted, affecting the flexibility and adaptability of our documentation.
• Inefficient publishing process: The publishing workflow was complex, involving multiple steps that added unnecessary delays.
• Broken editing experience: The lack of synchronization with GitLab source files resulted in a fragmented editing process.
• Costly enhancements: Implementing any changes or enhancements in Readme often proved to be expensive, making it challenging to adapt the tool to evolving documentation needs.

The Solution: Transitioning to Mintlify

Recognizing the challenges we faced, I conducted a thorough evaluation of various documentation tools, including Redocly, Docusaurus, GitBook, and Mintlify. While Docusaurus stood out as a strong option, it required dedicated developers to build and maintain the infrastructure, which posed significant challenges in terms of cost, implementation time, and resource allocation—especially without any developers available to assist. In the end, Mintlify emerged as the best choice. It offered all the features we needed and more, while also being a cost-effective solution compared to a single instance of Readme.

Key features and benefits of Mintlify

1. Collaborative review process: Mintlify supports real-time collaborative reviews, allowing multiple stakeholders to review and edit content simultaneously. This feature ensures accuracy, consistency, and faster turnaround times for content creation.
2. Local and staging previews: With Mintlify, writers can preview changes locally before merging them into production. This capability reduces the need for post-publish corrections and enhances the reliability of our documentation.
3. Customizable user interface: Mintlify offers extensive customization options, enabling us to align our documentation with our brand and user needs. This flexibility ensures that our documentation is both functional and visually appealing.
4. Streamlined publishing process: The publishing workflow in Mintlify is straightforward and efficient, allowing us to push updates more frequently and reliably. Individual changes can be promoted without affecting other files on staging, reducing complexity and delays.
5. Seamless integration with GitLab: Mintlify’s seamless integration with GitLab creates a cohesive documentation ecosystem. The editing experience is synchronized with source files, providing a smoother and more efficient workflow.
6. Mintlify developer pipeline for YAML validation: Mintlify includes a developer pipeline that validates YAML files, ensuring accuracy and consistency across our documentation. This feature minimizes errors and supports a smooth publishing process.
7. Efficient YAML management: Unlike Readme, which required a single compiled YAML file and running scripts to combine all YAML files, Mintlify allows us to manage individual YAML files without the need for complex scripts. This has saved significant time and made our YAML files more usable and easier to review.
8. AI-powered search: Mintlify’s AI search feature significantly enhances content discoverability, allowing users to quickly find relevant information, which improves the overall user experience.
9. Cost efficiency:? Moving toMintlify saved us around $40,000 annually in subscription costs alone. Achieving the same functionality with Readme would have required two instances and custom development work, significantly increasing our expenses. This cost saving excludes the additional savings gained by reducing our reliance on developer resources.

Strategic Planning and Operational Excellence

The success of our transition to Mintlify is a testament to the? strategic planning and commitment to operational excellence. By addressing multiple challenges with one efficient solution, we have transformed our documentation process, significantly enhancing both productivity and user experience. Key metrics that highlight this success include:

• Workflow and satisfaction: 67% of participants reported full satisfaction with Mintlify, with significant workflow improvements due to a centralized GitLab repository.
• Collaborative review: The collaborative review feature was highly effective, improving documentation accuracy and quality.
• Time savings: Participants estimated time savings of up to 75% in publishing new content.

Looking Ahead

Our journey with Mintlify is just beginning, and Phase 1 has established a robust foundation. We are committed to continuous improvement, with plans to:

• Optimize AI search: Enhance the AI-powered search functionality for more accurate and relevant results. This will involve using Mintlify's advanced content management capabilities to enrich metadata and datasets, ultimately improving search accuracy.
• Revamp documentation site structure: Leverage Mintlify's extensive customization options to redesign the site layout, ensuring a better user experience, improved navigation, and consistent messaging and branding.
• Reorganize content: UtilizeMintlify’s flexible content structuring features to organize guides, tabs, and layouts in a more meaningful way, without being restricted to certain content types.
• Implement Vale linter: Leverage centralized content management in GitLab to integrate Vale linter, enhancing code and content quality and ensuring consistency across all documentation moving forward.
• Integrate a search widget in the UI: Use Mintlify’s seamless integration capabilities to incorporate a search widget directly into the user interface, improving accessibility.
• Integrate search with JIRA: Leverage Mintlify’s integration features to track user feedback through JIRA, ensuring that feedback is efficiently converted into refined and updated content.

As we implement these enhancements, our documentation will continue to evolve to meet the needs of our users and developers. By leveraging Mintlify's capabilities, we're set to keep our documentation responsive and effective, ensuring it supports the ongoing development and success of our products.