Docs at Weaveworks: DX from open source to SaaS and beyond
0 likes136 views
Weaveworks offers Weave Cloud, a platform that enhances software team productivity through continuous delivery, visualization, troubleshooting, and monitoring. The documentation effort has evolved, moving towards a more structured approach inspired by Kubernetes to support both open source and SaaS product documentation. Challenges remain in coordinating updates across engineering and marketing teams to ensure documentation keeps pace with rapid development.
Docs at Weaveworks: DX from open source to SaaS and beyond
- 1. Docs at Weaveworks: DX from open source to SaaS and beyond Luke Marsden, Developer Experience @lmarsden
- 2. What does Weave do? Weave Cloud helps software teams iterate faster with: β’ Deploy: continuous delivery β’ Explore: visualize & troubleshoot β’ Monitor: Prometheus monitoring as a service
- 3. Meet the DX team Anita Mexico Docs Tamao SF Community Ilya London Code Luke London Lead
- 4. Once upon a timeβ¦ β’ Docker β’ Weave Net β’ Weave Scope β’ All open sourceβ¦
- 5. When I joined a year ago β’ Two repos on GitHub (net & scope) β’ Each repo has markdown files in it β’ WordPress marketing site with staging β’ βWordepressβ plugin we wrote to ship markdown docs to Wordpress β’ Net & scope devs could preview docs changes in staging
- 6. Types of documentation β’ Open source project docs β’ Guides β’ Step by step β’ Interactive labs (katacoda) β’ Marketing site copy β’ Blog posts
- 7. A word on Katacoda β’ Katacoda.com enables interactive labs β’ Minimizes βmean time to valueβ β’ Example: our continuous delivery demo requires Kubernetes, version control, container registry β’ Katacoda lets us bundle all of these in a preconfigured ephemeral environment, to get straight to the value
- 8. Problems β’ WordPress was slow and painful to change β’ Guides had horrific manual process to update
- 9. SaaS product β’ H2 2016: Weaveworks starts selling a SaaS subscription to Weave Cloud β’ Cloud = Flux + Scope + Cortex + Net + User mgmt + GUI β’ Docs needed to catch up
- 10. Solution β’ New website effort started H1 2017 with Sonja β’ Anita spearheaded Weave Cloud docs effort
- 11. Website βΒ Requirements β’ Marketing: need GUI interface for editing website copy, blog posts & SEO β’ DX: want to manage guides using markdown in GitHub with pull requests β’ Engineering: want to keep open source product docs in GitHub, need previews in those pull requests βΒ Ilya made this happen
- 12. Website βΒ Solution Netlify CI + CDN (or local builds in Docker) GitHub website- next repo Jekyll site Tutorials β¨ .md as part of website- next Built.io headless CMS copy, blogs & assets GitHub scope + net repos Scope + Net CI trigger preview URL from ref live site staging site preview URL per PR local build
- 13. Website βΒ Challenges β’ Builds are slow, pulls down all assets from Built.io every time β’ Builds arenβt 100% reliable or reproducible since fetching from built.io isnβt atomic β’ Overall a huge improvement though :-)
- 14. Weave Cloud docs β’ Anitaβs effort βΒ excellent work! β’ Inspired by Kubernetes docs structure β’ Concepts β’ Tasks β’ Tutorials β’ Reference β’ Great job of introducing concepts gradually
- 15. A note on WOUGs β’ WOUG = Weave Online User Group β’ We run online talks, trainings & meetups every week (and some in-person too!) β’ Tamao has done excellent work spearheading this effort β’ Real community building, demand generation for product, product feedback
- 16. Challenges β’ Hard to coordinate docs changes with engineering β’ Multiple teams, releasing continuously to SaaS service β’ Docs need to keep up β’ Experimenting with mailing list for coordination β’ Same challenge for marketing!
- 17. Weβre hiring DX in Bay Area! Great work/life balance, 20% open source, talks & content Email me :) [email protected]