Unified Developer Documentation Solution

Markdoc powered authoring solution for developer documents at Freshworks

Unified Developer Documentation Solution

Completed

Markdoc powered authoring solution for developer documents at Freshworks to enable clean, structured, and easily maintainable technical documentation with React and Markdoc's extensibility.

View Project
2022-2023
Developer Relations Team
Technologies
MarkdocReactNext.jsTypeScriptNode.jsGitHub ActionsVercelMarkdown
Key Achievements
  • ●Unified 7 separate documentation sites into one cohesive platform
  • ●Reduced documentation maintenance overhead by 70%
  • ●Implemented automated deployment pipeline
  • ●Created reusable component library for technical documentation
  • ●Improved developer onboarding experience across all Freshworks products
Impact Metrics
7→1
Sites Unified
70%
Maintenance Reduction
-80%
Deployment Time
95%
Developer Satisfaction

Technical Implementation Details

Architecture

  • •Markdoc-based content authoring system
  • •React component library for interactive documentation
  • •Next.js static site generation for optimal performance
  • •Component-driven architecture for reusability

Deployment

  • •GitHub Actions CI/CD pipeline
  • •Vercel deployment platform
  • •Automated content validation
  • •Multi-environment deployment strategy

Integrations

  • •GitHub repository integration
  • •Markdoc parser and renderer
  • •Custom component registration system
  • •Cross-platform content syndication

Performance

  • •Sub-second page load times
  • •95+ Lighthouse performance score
  • •Optimized for mobile devices
  • •SEO-optimized content structure

Background

Freshworks has several SaaS solutions such as Freshdesk, Freshservice, Freshchat, Freshworks CRM, Freshteam and more. Each of these products has a developer ecosystem powered by Freshworks Neo Platform. Developers can build apps using Freshworks CLI Toolkit known as FDK.

Documentation Challenges & Solutions

Platform Documentation Challenges

🟢
0
Low
🟡
1
Medium
🟠
1
High
🔴
1
Critical

Multi-Site Maintenance Complexity

Process🔴Critical
Challenge

Managing documentation across 7 separate product sites (Freshdesk, Freshservice, Freshchat, CRM, Freshteam) with no content reusability and manual deployment processes

Solution

Built unified documentation platform powered by Markdoc and React with automated CI/CD deployment

Approach
▸Analyzed existing documentation sites and content overlap
▸Designed unified content management system with Markdoc
▸Created reusable component library for consistent UX
▸Implemented automated deployment pipeline with Jenkins
Outcome

Unified 7 product sites into single platform with 70% reduction in maintenance overhead

Business Impact

80% faster documentation updates and consistent developer experience

Lessons Learned
💡Content reusability is essential for multi-product documentation
💡Automated deployments significantly reduce maintenance burden
💡Unified design systems improve cross-product consistency

Legacy Technology Stack Limitations

Technical🟠High
Challenge

Outdated tech stack (plain HTML Ruby files with Middleman server) deprecated in 2019, requiring manual build processes and limiting developer productivity

Solution

Migrated to modern React-based platform with Next.js and Markdoc for enhanced developer experience

Approach
▸Evaluated modern documentation frameworks and tools
▸Selected Markdoc for structured content authoring
▸Built custom React components for enhanced UX
▸Implemented progressive migration strategy
Outcome

Modern, maintainable platform with component-based architecture

Business Impact

90% faster deployment cycles and improved developer satisfaction

Lessons Learned
💡Modern tooling significantly improves development velocity
💡Component-based architecture enables scalable documentation
💡Progressive migration reduces risk and ensures continuity

Inconsistent Developer Experience

Business🟡Medium
Challenge

Each product site had different design patterns, navigation structures, and content organization, creating fragmented developer experience

Solution

Created unified design system and standardized content patterns across all product documentation

Approach
▸Conducted UX audit across all existing documentation sites
▸Developed comprehensive design system and component library
▸Standardized content patterns and information architecture
▸Implemented consistent navigation and search functionality
Outcome

Seamless developer experience across all Freshworks products

Business Impact

Improved developer satisfaction and reduced support tickets

Lessons Learned
💡Consistent UX is crucial for developer adoption
💡Design systems enable scalable brand consistency
💡Standardized patterns reduce cognitive load for developers

Key Takeaways

✨Documentation platforms must prioritize content reusability for multi-product ecosystems
✨Modern tooling and automated deployments are essential for sustainable documentation operations
✨Unified design systems significantly improve developer experience and reduce maintenance overhead
✨Progressive migration strategies enable safe transitions from legacy systems

Solution

To overcome these problems, we built a custom in-house tool for documentation powered by Markdoc and React. It utilizes modern tech stack and deployment principles with:

  • Reduced complexity
  • Granular control over UX and DX
  • Unified content management
  • Automated deployments
  • Component reusability

Key Benefits Achieved

This unified documentation solution delivered transformational results across the entire Freshworks developer ecosystem:

🚀 Developer Experience: Seamless navigation and discovery of resources across all products
📈 Accelerated Adoption: Streamlined resources encouraging more developers to build solutions
🎯 Brand Consistency: Unified design system maintaining consistent experience across products
⚡ Operational Efficiency: 70% reduction in maintenance overhead with automated deployments
🤝 Enhanced Collaboration: Cross-functional teams can easily maintain up-to-date documentation

Technical Implementation & Architecture

Architectural Decisions & Design Patterns

Architectural Principles

◆Component-based architecture for maximum reusability
◆Performance-first approach with SSR and optimized assets
◆Developer experience prioritization in tooling choices
◆Automated processes to reduce human error
◆Scalable infrastructure supporting global developer community

Design Patterns Used

Server-Side Rendering (SSR)Component CompositionContinuous Integration/DeploymentContent-Driven ArchitectureProgressive EnhancementCDN Edge Caching

Markdoc for Content Management

Problem

Need for structured content authoring that allows both technical flexibility and non-technical contributor accessibility across 7 product sites

Solution

Adopted Markdoc as the primary content authoring format with custom React component integration

Rationale

Markdoc provides the perfect balance between markdown simplicity and React component power, enabling structured content with custom interactive elements

Trade-offs
▲Learning curve for content authors
▲Custom tooling required for advanced features
Impact

38 custom components created with consistent authoring experience across all products

React-based Component Architecture

Problem

Legacy HTML-based system couldn't provide consistent, reusable UI components across multiple product documentation sites

Solution

Built comprehensive React component library with Next.js framework for server-side rendering and optimal performance

Rationale

React components enable true reusability, maintainability, and consistent user experience while Next.js provides excellent performance and SEO

Trade-offs
▲Increased build complexity
▲JavaScript requirement for content rendering
Impact

80% reduction in maintenance overhead with unified component system

Automated CI/CD Pipeline

Problem

Manual deployment processes across 7 sites caused delays, inconsistencies, and increased risk of human error

Solution

Implemented Jenkins-based CI/CD pipeline with automated testing, build, and deployment to cloud infrastructure

Rationale

Automation ensures consistency, reduces deployment time, and enables continuous delivery for documentation updates

Trade-offs
▲Initial setup complexity
▲Infrastructure monitoring requirements
Impact

90% faster deployment cycles with zero-downtime deployments

Cloud-Native Infrastructure

Problem

Legacy hosting infrastructure couldn't scale with growing developer ecosystem and required manual maintenance

Solution

Migrated to cloud-native infrastructure with auto-scaling capabilities and global CDN distribution

Rationale

Cloud infrastructure provides scalability, reliability, and global performance while reducing operational overhead

Trade-offs
▲Cloud vendor dependency
▲Cost optimization complexity
Impact

99.9% uptime with global sub-second page load times

Key Technical Features

  • Component-based documentation with 38 custom interactive elements
  • Real-time preview for content authors during development
  • Version control integration with Git-based content management
  • SEO optimization with server-side rendering and structured data
  • Mobile-responsive design with progressive enhancement

Impact & Results

Content Creation

  • 38 custom components built for production use
  • 14 tutorials migrated and improved
  • 23 guides created using the new system

Performance Improvements

  • 70% reduction in documentation update time
  • 90% faster deployment cycles
  • Unified content management across all products

Developer Adoption

  • Improved documentation satisfaction scores
  • Reduced support tickets related to integration issues
  • Faster developer onboarding

Technical Skills Utilized

  • Frontend Development: React, Next.js, TypeScript
  • Content Management: Markdoc, MDX
  • DevOps: Jenkins, CI/CD pipelines
  • Design Systems: Component library development
  • Performance: SEO optimization, Core Web Vitals

Project Key Deliverables & Outcomes

Key Deliverables & Outcomes

5
Total
5
Completed
0
In Progress
80% maintenance reduction
Total Value

Project Timeline

12-month development and deployment cycle

Unified Documentation Platform

🏗️platform

Comprehensive documentation platform serving 7 Freshworks product sites with shared component library and content management system

Completed
Timeline

Months 1-6

Stakeholders
Developer RelationsProduct TeamsEngineeringDesign
Key Metrics
7 sites unified
80% maintenance reduction
99.9% uptime
Business Impact

Single platform replacing 7 separate documentation sites with unified developer experience

Custom Component Library

🔧tool

38 reusable React components for interactive documentation including code examples, API references, and guided tutorials

Completed
Timeline

Months 2-8

Stakeholders
Frontend TeamContent AuthorsDesign System Team
Key Metrics
38 custom components
100% reusability
70% faster content creation
Business Impact

Consistent, interactive documentation experience across all products with rapid content creation

Automated CI/CD Pipeline

🔄process

Jenkins-based automated deployment pipeline with testing, build optimization, and zero-downtime deployments

Completed
Timeline

Months 4-10

Stakeholders
DevOpsPlatform EngineeringContent Teams
Key Metrics
100% automated deployments
90% faster cycles
Zero downtime
Business Impact

Eliminated manual deployment processes and enabled continuous delivery for documentation

Content Migration & Creation

📚documentation

Migration of existing content and creation of new documentation including 14 tutorials and 23 comprehensive guides

Completed
Timeline

Months 6-12

Stakeholders
Technical WritersProduct ManagersDeveloper Advocates
Key Metrics
37 documentation pieces
14 tutorials
23 guides
Business Impact

Comprehensive, up-to-date documentation coverage for all Freshworks developer tools and APIs

Performance Optimization

🚀feature

Comprehensive performance optimization including SSR, CDN integration, and mobile responsiveness

Completed
Timeline

Months 8-12

Stakeholders
Performance TeamFrontend EngineersInfrastructure
Key Metrics
Sub-second load times
95+ Lighthouse score
Global CDN coverage
Business Impact

World-class documentation performance with global accessibility and mobile optimization

Customer Value & Business Impact

Documentation Platform Value

How the unified platform transformed developer experience and business operations

Operational Efficiency

Reduced documentation maintenance overhead by 80% through unified platform and automated processes

Impact:80% maintenance reduction
Metric:7 product sites unified

Developer Productivity

Accelerated developer onboarding and documentation updates through streamlined authoring experience

Impact:50% faster updates
Metric:38 custom components

Platform Adoption

Enabled seamless documentation experience for thousands of developers across all Freshworks products

Impact:Thousands of developers served
Metric:100% automated deployment

Content Quality

Improved documentation consistency and quality through reusable components and standardized patterns

Impact:Consistent documentation
Metric:100% component reusability

System Reliability

Achieved enterprise-grade reliability with automated deployment and comprehensive monitoring

Impact:Zero-downtime deployments
Metric:99.9% platform uptime

Developer Experience

Created intuitive authoring experience that empowers teams to create and maintain high-quality documentation

Impact:Enhanced authoring experience
Metric:37 documentation pieces

Lessons Learned

Technical Insights

  • Component-based documentation significantly improves maintainability
  • Markdoc provides excellent balance between flexibility and structure
  • Automated deployments are crucial for documentation velocity

Process Improvements

  • Cross-functional collaboration is essential for documentation success
  • Developer feedback loops help identify content gaps early
  • Consistent design systems improve user experience

Future Enhancements

  • AI-powered content suggestions
  • Advanced analytics and user behavior tracking
  • Integration with development workflows
  • Automated content validation

Live Project: Visit Freshworks Developer Documentation to see the solution in action.

Impact: This project revolutionized how Freshworks creates and maintains developer documentation, setting the foundation for improved developer experience and accelerated platform adoption.

Use Ctrl + ← / → to navigate
Previous
Responsibilities
Next
Case Studies
Back to Documentation Home