This insight emerged from a discussion about documentation format choices and why teams consistently return to markdown after trying various content management systems.
Copy link
Core Insight
"We tried three different CMSs and always came back to markdown" - Dustin Younse
Despite initial resistance and the learning curve for non-technical contributors, markdown consistently proves to be the most sustainable choice for design system documentation.
Copy link
Why Teams Return to Markdown
Copy link
Universal Compatibility
✓ Cross-platform support - Works across Storybook, Zero Height, and custom documentation sites
✓ Tool independence - Not locked into specific vendor solutions
✓ Future-proof format - Readable by humans and machines for decades
Copy link
AI and Automation Ready
✓ MCP compatibility - Built-in support for Model Context Protocols
✓ Structured content - Easy for AI systems to parse and understand
✓ Version control integration - Documentation versions with code changes
Copy link
Single Source of Truth
✓ Multi-platform distribution - Same content published to multiple destinations
✓ Consistent formatting - Standardized presentation across tools
Dustin Younse (Indeed): "We tried three different CMSs and always came back to markdown... It's the lowest common denominator that a lot of different tools can interact with."
Kristen Singh (Intuit): "We came to the realization that Markdown was super powerful... through many, many errors. We have to train designers who are writing content on how to write in markdown, which is not easy. But the payoff is significant."
Copy link
When to Choose Markdown
Starting new documentation sites
Migrating from proprietary tools
Preparing for AI integration
Building multi-platform documentation
Teams prioritizing long-term sustainability
Copy link
Alternative Approaches Considered
Custom CMS Solutions
Full control over features and presentation
"Maintenance burden is pretty immense" - requires ongoing technical investment
WYSIWYG Editors
Non-technical contributors love the familiar interface
Updates and migrations become difficult over time
Proprietary Tools
Rich features and polished interfaces
"Try opening a Sketch file 5 years later. Good luck." - vendor lock-in risks
Copy link
Implementation Reality
The Learning Curve Challenge:
Teams must train designers and content creators on markdown syntax, which creates initial resistance.
The Long-term Payoff:
Once teams adopt markdown workflows, they gain unprecedented flexibility and future-proofing for their documentation.
Takeaway: Markdown isn't just a format—it's the foundation for future-proof, AI-ready design system documentation that scales across teams and tools. The initial learning curve pays dividends in long-term flexibility and sustainability.
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.
Markdown as Universal Language for Design Systems
Session: Craft Across: Documentation in Design Systems
Date: August 7, 2025
Key Contributors: Dustin Younse (Indeed), Kristen Singh (Intuit)
This insight emerged from a discussion about documentation format choices and why teams consistently return to markdown after trying various content management systems.
"We tried three different CMSs and always came back to markdown" - Dustin Younse
Despite initial resistance and the learning curve for non-technical contributors, markdown consistently proves to be the most sustainable choice for design system documentation.
Dustin Younse (Indeed): "We tried three different CMSs and always came back to markdown... It's the lowest common denominator that a lot of different tools can interact with."
Kristen Singh (Intuit): "We came to the realization that Markdown was super powerful... through many, many errors. We have to train designers who are writing content on how to write in markdown, which is not easy. But the payoff is significant."
Custom CMS Solutions
WYSIWYG Editors
Proprietary Tools
The Learning Curve Challenge: Teams must train designers and content creators on markdown syntax, which creates initial resistance.
The Long-term Payoff: Once teams adopt markdown workflows, they gain unprecedented flexibility and future-proofing for their documentation.
Takeaway: Markdown isn't just a format—it's the foundation for future-proof, AI-ready design system documentation that scales across teams and tools. The initial learning curve pays dividends in long-term flexibility and sustainability.
Source: Craft Across: Documentation in Design Systems • August 7, 2025