tech writing in a continuous deployment environment
TRANSCRIPT
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/