This talk covers how we run docs at Weaveworks, showing the migration from a legacy Wordpress environment to a new pipeline based system with a headless CMS. The slides also touch on how we run our online user group.

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 :) luke@weave.works