Infa Logo

Documentation Performance: The Hidden Adoption Killer

How performance issues kill documentation adoption and the custom solutions teams build to solve them.

Event Context

Session: Craft Across: Documentation in Design Systems
Date: August 7, 2025
Key Contributors: Dustin Younse (Indeed), Farid Sabitov (Infa)

This insight emerged from a discussion about the hidden performance costs of beautiful documentation and how they impact team productivity.

Core Insight

"3-10 second embed load times were unacceptable" - Dustin Younse

Performance directly impacts documentation adoption. Teams abandon slow documentation regardless of how comprehensive or well-designed it is.

The Performance Problem

Teams invest heavily in beautiful documentation, but performance issues kill adoption:

Common Performance Bottlenecks

  • Figma embeds - Load entire application per embed
  • Storybook embeds - 3-10 second render times for component examples
  • Third-party iframes - Unpredictable performance and security constraints
  • Large images and assets - Slow page loads across devices, especially mobile

Real-World Impact

  • Developer productivity - Slow docs create friction in development workflows
  • Team adoption - Teams create workarounds instead of using official documentation
  • Mobile accessibility - Performance issues are magnified on mobile devices
  • Enterprise constraints - Security and scale requirements add complexity

The Solution Pattern

1. Identify Performance Bottlenecks

Measure what matters:

  • Page load times for critical documentation pages
  • Embed render times for component examples
  • Search result response times
  • Mobile performance metrics

2. Build Custom Preview Systems

Instead of generic embeds:

  • Static screenshots with links to live examples
  • Custom component preview components
  • Lazy loading for non-critical content
  • Optimized images and assets

3. Optimize for User Context

Different users need different experiences:

  • Designers - High-fidelity previews and design details
  • Developers - Code examples and API documentation
  • Product teams - Usage guidelines and constraints
  • Mobile users - Fast-loading, essential information

Key Speaker Insights

Dustin Younse (Indeed): "We were really kind of behind the curve because just that, like the proprietary information angle of things... We had to wait until contracts were signed before we could even start touching these things."

Farid Sabitov (Infa): "With Infa you can measure that adoption, but if you want to measure usage, you can use Figma Analytics... but it won't tell you the adoption per product."

Real Impact at Scale

Indeed's Experience:

  • Lost access to Figma Dev Mode due to cost constraints for large engineering teams
  • "We had a million Excel files" for tracking design-code connections
  • Built custom preview systems that rendered instantly
  • Prioritized performance over visual fidelity for developer workflows

When to Prioritize Performance

  • Documentation pages taking more than 3 seconds to load
  • Teams complaining about slow embed performance
  • Mobile users reporting poor documentation experience
  • Enterprise teams with security and scale constraints
  • High-traffic documentation with many concurrent users

Performance Optimization Example

Before Optimization:

  • Figma embed: 8-second load time
  • Storybook embed: 5-second render time
  • Page load: 12 seconds total
  • Result: Teams avoid using documentation

After Optimization:

  • Custom preview component: Instant render
  • Static screenshot with link: 2-second load
  • Page load: 3 seconds total
  • Result: Daily documentation usage increases

Alternative Approaches

Ignore Performance Issues

  • Beautiful, comprehensive documentation
  • Unusable for daily workflows due to speed

Generic Embeds Everywhere

  • Consistent experience across all content
  • Consistently slow performance kills adoption

Remove All Interactive Examples

  • Fast loading times
  • Less useful documentation without live examples

Implementation Strategy

  1. Audit current performance - Identify the biggest bottlenecks
  2. Prioritize by user impact - Focus on most-used pages first
  3. Build custom solutions - Create lightweight alternatives to heavy embeds
  4. Measure and iterate - Track performance improvements and user satisfaction

Takeaway: Documentation performance isn't a nice-to-have—it's table stakes for adoption. The most beautifully designed documentation fails if teams won't wait for it to load. Performance optimization should be part of every documentation strategy from day one.

Source: Craft Across: Documentation in Design Systems • August 7, 2025

Documentation Performance: The Hidden Adoption Killer - Infa