This insight emerged from a discussion about the hidden performance costs of beautiful documentation and how they impact team productivity.
Copy link
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.
Copy link
The Performance Problem
Teams invest heavily in beautiful documentation, but performance issues kill adoption:
Copy link
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
Copy link
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
Copy link
The Solution Pattern
Copy link
1. Identify Performance Bottlenecks
Measure what matters:
Page load times for critical documentation screens
Embed render times for component examples
Search result response times
Mobile performance metrics
Copy link
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
Copy link
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
Copy link
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."
Copy link
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
Copy link
When to Prioritize Performance
Documentation screens 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
Copy link
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
Copy link
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
Copy link
Implementation Strategy
Audit current performance - Identify the biggest bottlenecks
Prioritize by user impact - Focus on most-used screens first
Build custom solutions - Create lightweight alternatives to heavy embeds
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
Content Feedback
Feedback on selected content
Close
Anonymous submissions are auto-posted to #feedback channel. You can also share directly in Slack.
Documentation Performance: The Hidden Adoption Killer
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.
"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.
Teams invest heavily in beautiful documentation, but performance issues kill adoption:
Measure what matters:
Instead of generic embeds:
Different users need different experiences:
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."
Indeed's Experience:
Before Optimization:
After Optimization:
Ignore Performance Issues
Generic Embeds Everywhere
Remove All Interactive Examples
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