tech writing in a continuous deployment environment

CHRISTINE BURWINKLE • IX TEAM LEAD • ATLASSIAN

Tech writing in a continuous deployment world

Hello!

About me• Team lead for tech writers

at Atlassian• Previously: • Employed at HP• Worked in DITA/XML

• M.S. in Tech Comm from Northeastern University

So… let’s talk about

terminology

Continuous deployment - what does this mean? • A philosophy/approach• All about short cycles and getting features out quickly• Get customer feedback during dev cycle• Ship small pieces experimentally or in phases

• Code in production-ready state• Shipping relies on a deployment pipeline• Allows n releases per day

Getting customer feedback during the dev cycle

Continuous deployment is not• Agile• Continuous integration• Continuous delivery

What does all this mean for a

tech writer?

What this can mean for tech writers• More uncertainty• Developers don’t necessarily know when a feature will be released• Product managers don’t necessarily know when a feature will be released• In fact, a feature can be released “magically”

• Documenting small pieces of work means that we have to become more efficient• Adapt to shifts in feature designs• Fewer (any?) “big” releases• Lots more work to track

What have we done to adapt?

1 - A mental shift• Features over releases• Releases become a parallel milestone to track• This aligns with how customers think anyway

Rel

ease

2 - Tooling can help. A lot. • It’s vital to be able to adapt to changes quickly• The right processes can help keep docs production-ready (just like code)

3 - The quest for a doc MVP• MVP = Minimal Viable Product• In product often means shipping in iterations

• What does this mean for doc? • Release notes > doc• Notes, banners > rewrites• Being transparent with customers helps• Feedback channels are vital

4 - Killing doc debt is key• Being ruthless about screenshots• Being ruthless about isolating information - say it once!• Blitzes can be effective for big changes

5 - Finding balance between control & freedom• Keeping doc review processes lean helps writers respond more quickly • Multiple review cycles seem unlikely to hold up • Hiring and empowering the right people is key

What are we still learning?

The right balance for iterations• Experiments, labs, and opt-in features are still tricky beasts

Resources & velocity• Resource-heavy content (like videos, tutorials) are even harder to maintain• Velocity on long-term projects is harder to maintain

What does MVD look like? • Define some guidelines and ideas for

minimally viable docs

Using in-app help• Including information in app can help lighten

the doc load

Defining a documentation pipeline• Automating doc publication• What are the right channels? • Tooling/technology requirements• Domain knowledge requirements

Other resources

Interesting reading• http://blogs.atlassian.com/2014/04/practical-continuous-deployment/• https://puppetlabs.com/blog/continuous-delivery-vs-continuous-deployment-whats-diff• http://radar.oreilly.com/2009/03/continuous-deployment-5-eas.html• http://www.wired.com/2013/04/linkedin-software-revolution/

Thank you!

CHRISTINE BURWINKLE • IX TEAM LEAD • CBURWINKLE@ATLASSIAN.COM