docops: documentation at the speed of agile

DocOpsDocumentation

at the Speed of Agile

for Keep Austin Agile 2016

Hello!

I am Mary ConnorI 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 doc2. Super pig3. Def of done

Hardening sprints to do docs?

Docs having separate sprints?

What is “DocOps”?DevOps for documentation

orHow 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 updatesPush 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 aggregationPull together all content, from sales and marketing through support and training

5 Customer integrationInvolve 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. Versions3. 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 needed1 - Nice to have2 - Need it later3 - Need it next year/release4 - Need it now5 - Critical need

Cost:$ - Per writers only$$ - Per extended team$$$ - Per all Agile teams

Score:0 - Fails requirement1 - Weak support2 - Some support3 - Half supports4 - Mostly supports5 - Complete support

“1 Prune & rank

requirementsScorecard 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 withLet 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 planDo 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 designThis 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 #e8004cBlue #00acc3 Aqua #00d1c6 Lime #bbcd00Green #65bb48 Gray #617a86 Light Gray #a1becc