Katara AI and Partisia Blockchain: A Documentation Transformation Story

The Challenge

In the rapidly evolving blockchain landscape, Partisia Blockchain stood out with its innovative approach to privacy-preserving computation and secure multiparty computation (MPC). However, like many cutting-edge technology companies, they faced a common yet critical challenge: their documentation was scattered and difficult to comprehend, falling short of industry standards despite their technological sophistication.

The documentation landscape mirrored a common pattern in the tech industry - a collection of information that had grown organically over time, written by different teams with varying approaches to documentation. This resulted in an inconsistent user experience that made it challenging for developers to fully leverage Partisia's powerful blockchain platform.

Discovery and Analysis

When Katara AI began working with Partisia, our first step was a comprehensive analysis of their existing documentation. This investigation revealed several key issues:

1. Inconsistent Structure: Documentation was organized without a clear framework, making navigation difficult for users
2. Mixed Content Types: Technical references, tutorials, and conceptual explanations were often intermingled in the same documents
3. Varying Depth: Some topics had excessive detail while others lacked crucial information
4. Unclear User Journeys: There was no clear path for users with different levels of expertise

Through careful keyword analysis, we gained deeper insights into the documentation's current state and identified patterns in how information was presented and accessed.

The Diataxis Solution

After evaluating various documentation frameworks, we determined that the Diataxis framework would be ideal for restructuring Partisia's documentation. Diataxis provides a clear methodology for organizing documentation into four distinct types:

• Tutorials (Learning-oriented)
• How-to Guides (Problem-oriented)
• Explanations (Understanding-oriented)
• Reference (Information-oriented)

This framework aligned perfectly with our goal of creating a more intuitive and accessible documentation experience for Partisia's users.

The Implementation Challenge

One of the most significant challenges we faced was the manual process of reorganizing and rewriting documentation. Without a standardized approach, previous documentation efforts had resulted in:

• Hybrid documents that tried to serve multiple purposes simultaneously
• Inconsistent tone and writing style across different sections
• Unclear distinctions between reference material and instructional content
• Redundant information spread across multiple locations

The manual nature of documentation work meant that each piece needed careful evaluation and thoughtful restructuring. Our team had to make numerous judgment calls about how to split and reorganize content while maintaining technical accuracy and improving clarity.

The Transformation Process

Our approach involved several key steps:

1. Document Classification: We analyzed each piece of content and classified it according to the Diataxis framework
2. Content Splitting: We carefully separated hybrid documents into their appropriate categories
3. Gap Analysis: We identified areas where additional content was needed
4. Standardization: We implemented consistent formatting and writing styles across all documentation
5. User Path Creation: We developed clear learning paths for different user types

Results and Impact

The transformation of Partisia's documentation yielded significant improvements:

• Clear Navigation: Users can now easily find the type of documentation they need
• Consistent Structure: Each document type follows a clear format and purpose
• Improved Learning Path: New users can follow a logical progression from tutorials to reference material
• Reduced Redundancy: Information is now organized efficiently with clear cross-references
• Better Maintenance: The structured approach makes it easier to update and maintain documentation

‍

Documentation Classification Process

‍

Content Restructuring Workflow

‍

‍

Lessons Learned

This project highlighted several important insights about documentation transformation:

1. The importance of a structured framework for organizing technical documentation
2. The value of clear separation between different types of documentation
3. The challenge of maintaining consistency when manually processing documentation
4. The need for systematic approaches to documentation management

Looking Forward

The success of this project has established a strong foundation for Partisia's future documentation efforts. The clear structure and organization principles put in place will make it easier to:

• Add new documentation as the platform evolves
• Maintain consistency in documentation style and structure
• Provide better support for developers and users
• Scale documentation efforts efficiently

Through this partnership, Katara AI has helped Partisia Blockchain transform their documentation from a potential barrier to adoption into a valuable asset that supports their users and showcases their innovative technology.

‍

Written By: 0xSero
Originally posted here: https://hackmd.io/@0xSero/BJLyPLftyx