devops docs: fast, great content for the cloud

DevOps Docs: Vanessa Wilburn 1#stc16 IBM Cloud

DevOps Docs: Fast, Great Content for the Cloud

Vanessa WilburnSenior Content Strategist, IBM

DevOps Docs: Vanessa Wilburn 2#stc16

Agenda

• Introduction to DevOps documentation

• Faster publication

• Quality when you have little time

• Your questions answered

• These slides: http://bit.ly/22dYWHL

3DevOps Docs: Vanessa Wilburn#stc16

Introduction to DevOps documentation


How cloud products are different

• Constantly changing GUI and features

• No version or release numbers• No deadlines or constant

deadlines, depending on your perspective

• No installation• Available across a network:

public cloud, dedicated cloud (increased security), or local cloud (behind a firewall)


How DevOps fits in*

• Design thinking: sponsor users, hills, stories• Minimum viable product (MVP)• Automated, continuous delivery• Continuous improvement: pivoting, failing fast• Data-driven decisions, hypothesis-driven development• Ranked backlogs• Co-located squads

*A one-size-fits-all approach doesn’t exist. Some DevOps practices might work for your team, but others might not. For example, co-located squads aren’t always a viable option. In that case, the key is to form a shared group culture.


What cloud docs look like: web-based & interactive• Embedded video, interactive diagrams, code

snippets that you can copy easily• Getting started info• Tutorials• Reference docs


What cloud docs look like: social


Faster publication


Automation

• DevOps toolchain – Automatic doc builds, tests, and

deployments– Deployments on internal and

external servers

• Builds by Jenkins – Library (plugins/folders) built

automatically: by our team’s instance and a shared instance

– Our own Jenkins, avoiding others’ bursts, outages, and space contention

– Multiple staging environments for unique requirements


Tooling

• Content Management Systems– Dita-aware CMS – GitHub

• Development source: markdown readme’s, python files for Swagger docs, error messages, and CLI help

• Social docs in markdown• Authoring tools: Oxygen,

Atom, PyCharm, text editors

• Kanban boards for sprint planning • Ways to track doc issues: Doc impact field or tagging


Content strategy interpreted from Spotify

• Minimum viable product (MVP)– Think more. Write less.– Progressive disclosure

and embedded content– Top use cases for

majority of users– Stopped overwhelming

users with "nice to know" info

• Iterative translation: monthly shipments with build files

• Paired writers – Higher quality with two

sets of eyes– Coverage during

vacations and illnesses

• Collaborative authoring with developers– Pull requests on Dev

files, such as yaml, json, and python


Quality when you have little time


Tools to catch low-hanging fruit

• Grammar, style, spelling• Accessibility tools• Link checkers• Validation with user testing

Use these tools regularly to achieve quality by iterative testing.Dashboards roll up on-going operational quality.


Grammar, style, spelling

• Acrolinx IQ– Checks files of many types– You can use it within

Oxygen Editor or standalone

– Checks dictionaries, style guidelines, etc.

– Batch tools and reports


Accessibility

• Enable people with different abilities

• Comply with government requirements and industry standards

• Examine content and address accessibility violations

• Tools: Rational Policy Tester (RPT), Digital Content Checker, or Automated Accessibility Tester


Link checking

• Links break. Links break all the time in the Cloud

• Many tools available from the web


Low-cost user feedback

• Low-fi testing early and often: paper prototypes, sketches, design walk through’s, and partnerships with UX designers

• Sources for feedback– Internal users– Forums on Stack Overflow– Meetups– Conferences

• Open and closed betas• Traditional feedback button on docs


Business impact of content: metrics and KPIs

• Acquisition and conversion of customers • Self-help and support-call diversion• Engagement and reach


Acknowledgements

Thanks go to my IBM collaborators for their contributions to these slides:• Sue Graham• Laura Hinson

© Copyright Vanessa Wilburn


Check it out

• Steve Krug. Don’t Make Me Think, Second Edition• Spotify engineering culture:

– https://labs.spotify.com/2014/03/27/spotify-engineering-culture-part-1/• #STC16:

– Elizabeth Fraley. How Do I Pick the Right Tool for Me?– Tanya Ivanova and Barry Grenon. Automate Release Notes for Quick and

Accurate Results– Abhishek Jain. Do More with Less and Increase Your ROC

https://labs.spotify.com/2014/03/27/spotify-engineering-culture-part-1/

https://labs.spotify.com/2014/03/27/spotify-engineering-culture-part-1/


Your questions answered

Vanessa Wilburn• [email protected]• LinkedIn: https://www.linkedin.com/in/vanessawilburn

As an Information Architect and Content Strategist for IBM Cloud, I deliver the content experience in the form of user interfaces, web-based information, product manuals, and other self-service information. I design and run usability tests to assess how users experience "content on the glass." The design work includes user flows, personas, prototypes, and taxonomies. Moreover, I've performed duties as a Project Lead, Technical Lead, and Technical Editor in support of IBM software.

devops docs: fast, great content for the cloud

Software