Upload
vanessawilburn
View
127
Download
2
Embed Size (px)
Citation preview
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
DevOps Docs: Vanessa Wilburn 4#stc16
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)
DevOps Docs: Vanessa Wilburn 5#stc16
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.
DevOps Docs: Vanessa Wilburn 6#stc16
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
DevOps Docs: Vanessa Wilburn 7#stc16
What cloud docs look like: social
8DevOps Docs: Vanessa Wilburn#stc16
Faster publication
DevOps Docs: Vanessa Wilburn 9#stc16
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
DevOps Docs: Vanessa Wilburn 10#stc16
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
DevOps Docs: Vanessa Wilburn 11#stc16
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
12DevOps Docs: Vanessa Wilburn#stc16
Quality when you have little time
DevOps Docs: Vanessa Wilburn 13#stc16
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.
DevOps Docs: Vanessa Wilburn 14#stc16
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
DevOps Docs: Vanessa Wilburn 15#stc16
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
DevOps Docs: Vanessa Wilburn 16#stc16
Link checking
• Links break. Links break all the time in the Cloud
• Many tools available from the web
DevOps Docs: Vanessa Wilburn 17#stc16
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
DevOps Docs: Vanessa Wilburn 18#stc16
Business impact of content: metrics and KPIs
• Acquisition and conversion of customers • Self-help and support-call diversion• Engagement and reach
19DevOps Docs: Vanessa Wilburn#stc16
Acknowledgements
Thanks go to my IBM collaborators for their contributions to these slides:• Sue Graham• Laura Hinson
© Copyright Vanessa Wilburn
20DevOps Docs: Vanessa Wilburn#stc16
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
21DevOps Docs: Vanessa Wilburn#stc16
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.