DocOps
Documentation
at the Speed of Agile
for Keep Austin Agile 2016

Hello!
I am Mary Connor
I am here because I love both documentation and Agile.
You get cats, too. You can find me at www.cleverhamster.com

Our Scope
Agile docs
DocOps
Building it

What are
Agile Docs?
or
Don’t we get to stop doing docs?
1

“Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
~ Agile Manifesto

True: Agile means we write less.

“Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
~ Agile Manifesto

Documentation = Internal
to project development
Project plans
Requirements
Functional
specifications
Design specifications
Feature proposals
Reference artifacts
Test:
“Will customers ever
see it?”

Documentation is
part of “software”,
regardless of source
“software” = CX* deliverable
*Customer Experience
CX = GUI + API + outputs
+ information interface (IX)
◉ Prefer shippable Help over
specifications,
working user assistance over
project artifacts
◉ Ideal: Write the docs first!
Videos
Support
API
Help
GUI
Working
Software
Outputs
Tooltips

In Agile docs,
where are the writers?
◎ Who has writers on scrum teams?
◎ If not, where do you put them?
◎ Regardless,
they are pigs

New Role:
Writer as Super Pig
❏ Invite and expect them to act as
pig on team(s)
❏ Most important:
co-owner of info products
❏ UI: Co-owner of UI languaging
❏ UX: User advocate on design
❏ CX: Manage own doc epics
❏ PO: Write Help epics (dev task)
© Melissa Burpo

Status
Release Note
Gotta Make it Happen
Definition of Done
= Ready to ship:
❏ Release Note
❏ Critical facts
❏ Happy path
procedure
Sprint Review
= Ready to demo:
❏ Show relnotes
❏ Show visuals
❏ Have writer demo
new feature
Code Test Doc DoneTo Do
Swarm supports encoding of non-ASCII characters
for object metadata and for metadata searching.
1
2
Your tool
to track
stories

“Yeah, but what about....”
Docs lagging
a sprint?
Remember:
1. Lean doc
2. Super pig
3. Def of done
Hardening
sprints to do
docs?
Docs having
separate
sprints?

What is “DocOps”?
DevOps for documentation
or
How to always be shippable
2

A definition of DocOps:
“Reengineering docs
to support Agile flow”
1. Aspiration: Like DevOps, bring
IT process automation to authoring
2. Shorthand: a documentation platform
that delivers near real-time docs

5 elements of DocOps*
1 Agility
2 Continuous updates
3 Collaborative authoring
4 Content aggregation
5 Customer integration
* https://docops.ca.com

The Key Three
1 Agility
Respond to code changes right away
(minutes, not months)
2 Continuous updates
Push fixes immediately, trigger translation
when needed
3 Collaborative authoring (ouch)
Invite the crowd, surrender ownership:
empower team to add and fix content

Extra Credit:
4 Content aggregation
Pull together all content, from sales and
marketing through support and training
5 Customer integration
Involve customer support and feedback;
analyze usage and statistics

CA case study
DocOps platform that is a
"wiki++"
◎ friendly wiki (Confluence) +
◎ powerful extensions:
◉ standardization (editing)
◉ publication
◉ translation

CA’s Immediate Results
25% word count savings [lean]
(via consolidation)
25% efficiency gains [automation]
(from trimming doc activities
now obsolete or automated)
55% faster translation turnaround

CA’s DocOps Pieces
Collaborative
authoring and
aggregation:
Atlassian
Confluence
Doc production:
k15t Scroll,
1. Acrolinx
integration
2. Versions
3. Exports for
deliverables
Automated
editing:
Acrolinx, for
simplified
technical English
(i18n) and
standardization
Translation
management:
Lingotek, for
workflow in and
out of the wiki
UI integration:
Product-specific
landing pages
integrate with
web app, using
single-sign-on
Communication
integration: Jive
communities,
Google Analytics,
Salesforce
support, LinkedIn
marketing, etc.

Success Criteria
1. Automatic outputs
◉ No-touch builds
◉ No-touch delivery
2. Single-sourcing
◉ Across products (reuse)
◉ Across outputs (HTML, PDF)
3. If it needs care but not judgment,
automate it!
Set it
and
forget it

Examples of doc
automations
Hourly builds and
refresh of intranet
Script to parse object
code into doc XML
Script to find and
format public settings
Build scripts to export
docs by release version
Add-on to link external
content, spreadsheets
WinMerge diffs to validate
release changes
Document!X code-comment
tool for Visual Studio, prompt
for missing descriptions
Use of variables and shared
chunks (Sandcastle ‘tokens’)
Auto-GET all before builds
Help links by object ID or
search term (fuzzy)

How Do I Build It?
Getting there from where you are
3

Where to start?
◎ Tool and platform choices
◎ Example stacks and outputs
◎ Practical requirements
(4 areas)
◎ Working with what you’ve got
◎ Being Agile

Tool stacks - local
Word source + Doc-To-Help build
FrameMaker/Word source + RoboHelp build
FrameMaker/Word source + WebWorks ePublisher
XHTML source +
Flare, RoboHelp, D2H, HelpStudio, H&M, … build
Confluence Server + Scroll Exporters (REST calls)
DITA XML + Open Toolkit scripts for outputs

New: Cloud Tools,
OSS, & “beta-ware”
ClickHelp w/ export API
Confluence Cloud (exports?)
HelpIQ, Paligo (automation?)
Readme.io (exports?)
HelpConsole.com (autopublishes)
Markdown source + Pandoc scripts
+ static site generator (Daux.io,
MkDocs, Jekyll)

“
DocOps out of the box?
Author-It
MindTouch
ZenDesk?

“
{handy source format}
+ {automated transform}
+ {version control}
[ + {translation management} ]

Agile Implementation
= easy to:
◎ Access (cloud or
hosted, work via
browser or terminal
server)
◎ Scale to more
users, higher usage
◎ Secure selectively
(serve both
customers and
staff)
◎ Support (hosted;
upgrade-proof
customizations)
◎ Integrate, set to
own domain, extend
non-destructively (API)
◎ Brand/skin (without
update breakage)
1

Agile Authoring
= easy to:
◎ Import rich
content created
elsewhere (legacy)
◎ Create topics
◎ Update topics
◎ Release (for SaaS,
queue up changes
for release-day
publication)
◎ Revert, compare
history
◎ Reuse content
(variables,
conditions,
different outputs)
◎ Embed media
(screenshots,
diagrams, slides,
video)
2

Agile Response
= easy to:
◎ Trace and and
autolink with
support cases
and dev issues
◎ Support
involvement
◉ Find
◉ Request
◉ Link
◎ Change
notifications, see
what changed
(diff)
◎ Comment
notifications and
management
◎ Analytics
reporting
3

Agile Self-Service
= easy to:
◎ Single-sign-on with
existing product
and support sites
◎ Search across all:
docs, blogs, forums
◎ Print what I want
◎ Export what I want
◎ Subscribe to what I
want
◎ Comment, give
feedback, rate/vote
◎ Translate on demand
◎ Use on any device
(responsive)
◎ Google to answers
4

Agile Requirements Matrix
Cost/month Access (3) Scale (2) Secure (5) TOTAL SCORE
OPTION A 3 × 4 2 × 5 5 × 1 35
OPTION B 3 × 1 2 × 2 5 × 5 32
Priority:
0 - Not needed
1 - Nice to have
2 - Need it later
3 - Need it next year/release
4 - Need it now
5 - Critical need
Cost:
$ - Per writers only
$$ - Per extended team
$$$ - Per all Agile teams
Score:
0 - Fails requirement
1 - Weak support
2 - Some support
3 - Half supports
4 - Mostly supports
5 - Complete support

“
1
Prune & rank
requirements
Scorecard of your Agile doc reqs,
ranked by urgency, to compare options
● Goal: Don’t compare tools but rather
platforms (tool stacks) against your
Agile requirements
● Notice: Total cost changes considerably
when scaled across the Agile team

“
2
Love the one
you’re with
Let your environment, legacy situation,
and IT resources set direction
● Tip: Product bundles might hide treasures;
explore enterprise licenses first (IT owns it)
● Do not be shamed into following cool kids
● Important: There is no right path

“
3
Working code
over plan
Do a proof-of-concept, then pilot
project, and keep tweaking
● Be agile! Resist pressure to produce a
waterfall Plan and Schedule
● Proof-of-concept + pilot reveal feasibility
● Decompose migration into epics with value

Thanks!
Questions? Reaching me:
maryconnor@gmail.com
@maryfconnor

Credits
Special thanks to all the people
who made and released these
awesome resources for free:
◎ Presentation template by
SlidesCarnival
◎ Photographs by Unsplash

Presentation design
This presentation uses the following typographies and colors:
◎ Titles: Nixie One
◎ Body copy: Varela Round
You can download the fonts on this page:
http://www.google.com/fonts/#UsePlace:use/Collection:Nixie+One|Varela+Round
Click on the “arrow button” that appears on the top right
Yellow #f8bb00 Orange #ed4a00 Fucsia #e8004c
Blue #00acc3 Aqua #00d1c6 Lime #bbcd00
Green #65bb48 Gray #617a86 Light Gray #a1becc