Docs at Weaveworks: DX from open source to SaaS and beyond

Luke Marsden, Developer Experience@lmarsden

What does Weave do?

Weave Cloud helps software teams iterate faster with: • Deploy: continuous

delivery • Explore: visualize &

troubleshoot • Monitor: Prometheus

monitoring as a service

Meet the DX team

Anita Mexico Docs

Tamao SF Community

Ilya London Code

Luke London Lead

Once upon a time…• Docker • Weave Net • Weave Scope • All open source…

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

Types of documentation• Open source project docs • Guides • Step by step • Interactive labs (katacoda)

• Marketing site copy • Blog posts

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

Problems• WordPress was slow and painful to

change • Guides had horrific manual process to

update

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

Solution• New website effort started H1 2017 with

Sonja • Anita spearheaded Weave Cloud docs

effort

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

Website – Solution

Netlify CI + CDN(or local builds in Docker)

GitHubwebsite-next repoJekyll site

Tutorials .md as part of website-next

Built.io headless CMScopy, blogs & assets

GitHubscope + net repos Scope + Net CI trigger

preview URL from ref

live site

staging site

preview URL per PR

local build

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 :-)

Weave Cloud docs• Anita’s effort – excellent work! • Inspired by Kubernetes docs structure • Concepts • Tasks • Tutorials • Reference

• Great job of introducing concepts gradually

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

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!

We’re hiring DX in Bay Area!

Great work/life balance, 20% open source, talks & content Email me :) luke@weave.works