DocOps: Documentation at the Speed of Agile
-
Upload
mary-connor -
Category
Technology
-
view
419 -
download
4
Transcript of 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:
@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