Unblocking your organization with diagrams-as-code
summary
Kong implements Mermaid via Jaal plugin to turn text into diagrams that live next to docs, with a four-writer one-tooling-engineer team supporting 13 product managers 150 engineers 30 support and seeing a noticeable rise in engineer-contributed diagrams. A proof-of-concept is copied into the Kuma repo adoption and rolled out org-wide, styling tweaked to match docs, accessibility handled via figure descriptions, and the approach saves time and actually works thanks to the mermaid live editor for iterative layout.
AI-written summary · about
chapters (20)
- 0:00Diagrams-as-code journey intro
- 1:25Traditional diagramming inefficiency
- 3:49Pain points with diagrams
- 7:45What is Mermaid and why consider it
- 9:30Proof of concept for action
- 12:00Docs as product for adoption
- 14:52Mermaid for Kuma team
- 17:23Community growth and improvements
- 18:48Lessons learned and future plans
- 19:51Q&A: Access, business case, complex diagrams
- 23:02Q&A: Designer views and Mermaid limits
- 25:31Q&A: Team resistance and engineer contributions
- 27:59Q&A: Engineer contributions and styling
- 29:09Q&A: Mermaid without full adoption
- 29:31Q&A: Diagram look and feel feedback
- 30:35Q&A: Version control and contributors
- 31:41Q&A: Diagram accessibility
- 32:25Q&A: Permission examples
- 33:29Q&A: Docs platform and hosting
- 34:13Q&A: Converting UI diagrams to Mermaid
related talks
51mDiagrams as code 2.0
44mAutomate your software design How far we can get and how the AI chan
45mA Picture is Worth 1000 Lines of Code
14mRethinking Designer-Developer Collaboration
01h 00mVisualise, document and explore your software architecture
01h 00mC4 models as code
33mRefactoring with Observability
30mAutomatic Visualizations of the Frontend