devops docs: fast, great content for the...

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

• Theseslides: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

• ContentManagementSystems– Dita-awareCMS– GitHub

•Developmentsource:markdownreadme’s,pythonfilesforSwaggerdocs,errormessages,andCLIhelp

• Socialdocsinmarkdown

• Authoringtools:Oxygen,Atom,PyCharm,texteditors

• Kanbanboardsforsprintplanning• Waystotrackdocissues:Docimpact fieldortagging


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

• Linksbreak.Linksbreakallthetime intheCloud

• Manytoolsavailablefromtheweb


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


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...

Documents