Vanessa Wilburn presented on strategies for faster publication and higher quality documentation for cloud products with tight deadlines. She discussed using automation, DevOps toolchains, and content management systems to streamline documentation processes. She also emphasized techniques like grammar checking, accessibility testing, and user feedback to improve documentation quality when time is limited. The presentation provided an overview of best practices for DevOps documentation adapted from Spotify's engineering culture.
1. DevOps Docs: Vanessa Wilburn 1#stc16 IBM Cloud
DevOps Docs: Fast, Great
Content for the Cloud
Vanessa Wilburn
Senior Content Strategist, IBM
2. 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
4. 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)
5. 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.
6. 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
9. 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
10. 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
11. 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
13. 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.
14. 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
15. 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
16. DevOps Docs: Vanessa Wilburn 16#stc16
Link checking
• Links break. Links break
all the time in the Cloud
• Many tools available
from the web
17. 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
18. 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
20. 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
21. 21DevOps Docs: Vanessa Wilburn#stc16
Your questions answered
Vanessa Wilburn
• wilburnvanessa@gmail.com
• 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.
