SlideShare ist ein Scribd-Unternehmen logo
1 von 41
Downloaden Sie, um offline zu lesen
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
DocOps: Documentation at the Speed of Agile
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

Weitere ähnliche Inhalte

Was ist angesagt?

Workshop Spring - Session 1 - L'offre Spring et les bases
Workshop Spring  - Session 1 - L'offre Spring et les basesWorkshop Spring  - Session 1 - L'offre Spring et les bases
Workshop Spring - Session 1 - L'offre Spring et les basesAntoine Rey
 
Eclipse RDF4J - Working with RDF in Java
Eclipse RDF4J - Working with RDF in JavaEclipse RDF4J - Working with RDF in Java
Eclipse RDF4J - Working with RDF in JavaJeen Broekstra
 
Building an Activity Feed with Cassandra
Building an Activity Feed with CassandraBuilding an Activity Feed with Cassandra
Building an Activity Feed with CassandraMark Dunphy
 
BigData_Chp3: Data Processing
BigData_Chp3: Data ProcessingBigData_Chp3: Data Processing
BigData_Chp3: Data ProcessingLilia Sfaxi
 
[2D1]Elasticsearch 성능 최적화
[2D1]Elasticsearch 성능 최적화[2D1]Elasticsearch 성능 최적화
[2D1]Elasticsearch 성능 최적화NAVER D2
 
DB Monitoring 개념 및 활용 (박명규)
DB Monitoring 개념 및 활용 (박명규)DB Monitoring 개념 및 활용 (박명규)
DB Monitoring 개념 및 활용 (박명규)WhaTap Labs
 
Battle of the frameworks : Quarkus vs SpringBoot
Battle of the frameworks : Quarkus vs SpringBootBattle of the frameworks : Quarkus vs SpringBoot
Battle of the frameworks : Quarkus vs SpringBootChristos Sotiriou
 
Twitter의 snowflake 소개 및 활용
Twitter의 snowflake 소개 및 활용Twitter의 snowflake 소개 및 활용
Twitter의 snowflake 소개 및 활용흥배 최
 
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...HostedbyConfluent
 
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013Introduction and Overview of Apache Kafka, TriHUG July 23, 2013
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013mumrah
 
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...Jemin Huh
 
Kafka Retry and DLQ
Kafka Retry and DLQKafka Retry and DLQ
Kafka Retry and DLQGeorge Teo
 
Disaster Recovery Plans for Apache Kafka
Disaster Recovery Plans for Apache KafkaDisaster Recovery Plans for Apache Kafka
Disaster Recovery Plans for Apache Kafkaconfluent
 
Spark (v1.3) - Présentation (Français)
Spark (v1.3) - Présentation (Français)Spark (v1.3) - Présentation (Français)
Spark (v1.3) - Présentation (Français)Alexis Seigneurin
 
Apache Kafka 0.8 basic training - Verisign
Apache Kafka 0.8 basic training - VerisignApache Kafka 0.8 basic training - Verisign
Apache Kafka 0.8 basic training - VerisignMichael Noll
 
twMVC#44 讓我們用 k6 來進行壓測吧
twMVC#44 讓我們用 k6 來進行壓測吧twMVC#44 讓我們用 k6 來進行壓測吧
twMVC#44 讓我們用 k6 來進行壓測吧twMVC
 

Was ist angesagt? (20)

Workshop Spring - Session 1 - L'offre Spring et les bases
Workshop Spring  - Session 1 - L'offre Spring et les basesWorkshop Spring  - Session 1 - L'offre Spring et les bases
Workshop Spring - Session 1 - L'offre Spring et les bases
 
Eclipse RDF4J - Working with RDF in Java
Eclipse RDF4J - Working with RDF in JavaEclipse RDF4J - Working with RDF in Java
Eclipse RDF4J - Working with RDF in Java
 
Building an Activity Feed with Cassandra
Building an Activity Feed with CassandraBuilding an Activity Feed with Cassandra
Building an Activity Feed with Cassandra
 
BigData_Chp3: Data Processing
BigData_Chp3: Data ProcessingBigData_Chp3: Data Processing
BigData_Chp3: Data Processing
 
[2D1]Elasticsearch 성능 최적화
[2D1]Elasticsearch 성능 최적화[2D1]Elasticsearch 성능 최적화
[2D1]Elasticsearch 성능 최적화
 
DB Monitoring 개념 및 활용 (박명규)
DB Monitoring 개념 및 활용 (박명규)DB Monitoring 개념 및 활용 (박명규)
DB Monitoring 개념 및 활용 (박명규)
 
Battle of the frameworks : Quarkus vs SpringBoot
Battle of the frameworks : Quarkus vs SpringBootBattle of the frameworks : Quarkus vs SpringBoot
Battle of the frameworks : Quarkus vs SpringBoot
 
Twitter의 snowflake 소개 및 활용
Twitter의 snowflake 소개 및 활용Twitter의 snowflake 소개 및 활용
Twitter의 snowflake 소개 및 활용
 
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...
Fan-in Flames: Scaling Kafka to Millions of Producers With Ryanne Dolan | Cur...
 
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013Introduction and Overview of Apache Kafka, TriHUG July 23, 2013
Introduction and Overview of Apache Kafka, TriHUG July 23, 2013
 
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...
서비스 모니터링 구현 사례 공유 - Realtime log monitoring platform-PMon을 ...
 
Kafka Retry and DLQ
Kafka Retry and DLQKafka Retry and DLQ
Kafka Retry and DLQ
 
Une introduction à Hive
Une introduction à HiveUne introduction à Hive
Une introduction à Hive
 
Disaster Recovery Plans for Apache Kafka
Disaster Recovery Plans for Apache KafkaDisaster Recovery Plans for Apache Kafka
Disaster Recovery Plans for Apache Kafka
 
Spark (v1.3) - Présentation (Français)
Spark (v1.3) - Présentation (Français)Spark (v1.3) - Présentation (Français)
Spark (v1.3) - Présentation (Français)
 
Apache Kafka 0.8 basic training - Verisign
Apache Kafka 0.8 basic training - VerisignApache Kafka 0.8 basic training - Verisign
Apache Kafka 0.8 basic training - Verisign
 
twMVC#44 讓我們用 k6 來進行壓測吧
twMVC#44 讓我們用 k6 來進行壓測吧twMVC#44 讓我們用 k6 來進行壓測吧
twMVC#44 讓我們用 k6 來進行壓測吧
 
すぐわかる HCL Nomad
すぐわかる HCL Nomadすぐわかる HCL Nomad
すぐわかる HCL Nomad
 
CQRS & EVS with MongoDb
CQRS & EVS with MongoDbCQRS & EVS with MongoDb
CQRS & EVS with MongoDb
 
HDFS Tiered Storage: Mounting Object Stores in HDFS
HDFS Tiered Storage: Mounting Object Stores in HDFSHDFS Tiered Storage: Mounting Object Stores in HDFS
HDFS Tiered Storage: Mounting Object Stores in HDFS
 

Ähnlich wie DocOps: Documentation at the Speed of Agile

Salesforce DevOps: Where Do You Start?
Salesforce DevOps: Where Do You Start?Salesforce DevOps: Where Do You Start?
Salesforce DevOps: Where Do You Start?Chandler Anderson
 
Backstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptxBackstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptxBrandenTimm1
 
Navigating the Mess of a Shared drive Migration to SharePoint
Navigating the Mess of a Shared drive Migration to SharePointNavigating the Mess of a Shared drive Migration to SharePoint
Navigating the Mess of a Shared drive Migration to SharePointJoanne Klein
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Den Delimarsky
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liuStreamNative
 
Platform engineering 101
Platform engineering 101Platform engineering 101
Platform engineering 101Sander Knape
 
Case Study: The Value of Partnership During Conversion
Case Study: The Value of Partnership During ConversionCase Study: The Value of Partnership During Conversion
Case Study: The Value of Partnership During Conversiondclsocialmedia
 
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...«Організація процесу розробки мобільного застосунку для аутсорсингової команд...
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...IT Weekend
 
Large drupal site builds a workshop for sxsw interactive - march 17, 2015
Large drupal site builds   a workshop for sxsw interactive - march 17, 2015Large drupal site builds   a workshop for sxsw interactive - march 17, 2015
Large drupal site builds a workshop for sxsw interactive - march 17, 2015rgristroph
 
Pat Farrell, Migrating Legacy Documentation to XML and DITA
Pat Farrell, Migrating Legacy Documentation to XML and DITAPat Farrell, Migrating Legacy Documentation to XML and DITA
Pat Farrell, Migrating Legacy Documentation to XML and DITAfarrelldoc
 
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint Solutions
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint SolutionsZero to 365 in One Hour: Processes and Tools for Effective SharePoint Solutions
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint SolutionsRegroove
 
Open Source Lessons from the TODO Group
Open Source Lessons from the TODO GroupOpen Source Lessons from the TODO Group
Open Source Lessons from the TODO GroupChris Aniszczyk
 
Software development process for outsourcing team
Software development process for outsourcing teamSoftware development process for outsourcing team
Software development process for outsourcing teamMykhail Galushko
 
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovix
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovixapidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovix
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovixapidays
 
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...Joanne Klein
 
Oscon 2016: open source lessons from the todo group
Oscon 2016: open source lessons from the todo groupOscon 2016: open source lessons from the todo group
Oscon 2016: open source lessons from the todo groupBen VanEvery
 
Maintainable Machine Learning Products
Maintainable Machine Learning ProductsMaintainable Machine Learning Products
Maintainable Machine Learning ProductsAndrew Musselman
 
A simple test paper from Chen
A simple test paper from ChenA simple test paper from Chen
A simple test paper from Chentechweb08
 

Ähnlich wie DocOps: Documentation at the Speed of Agile (20)

Salesforce DevOps: Where Do You Start?
Salesforce DevOps: Where Do You Start?Salesforce DevOps: Where Do You Start?
Salesforce DevOps: Where Do You Start?
 
The Road to DITA
The Road to DITAThe Road to DITA
The Road to DITA
 
Backstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptxBackstage at CNCF Madison.pptx
Backstage at CNCF Madison.pptx
 
Navigating the Mess of a Shared drive Migration to SharePoint
Navigating the Mess of a Shared drive Migration to SharePointNavigating the Mess of a Shared drive Migration to SharePoint
Navigating the Mess of a Shared drive Migration to SharePoint
 
Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018Docs as Part of the Product - Open Source Summit North America 2018
Docs as Part of the Product - Open Source Summit North America 2018
 
Agile presentation
Agile presentationAgile presentation
Agile presentation
 
Code the docs-yu liu
Code the docs-yu liuCode the docs-yu liu
Code the docs-yu liu
 
Platform engineering 101
Platform engineering 101Platform engineering 101
Platform engineering 101
 
Case Study: The Value of Partnership During Conversion
Case Study: The Value of Partnership During ConversionCase Study: The Value of Partnership During Conversion
Case Study: The Value of Partnership During Conversion
 
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...«Організація процесу розробки мобільного застосунку для аутсорсингової команд...
«Організація процесу розробки мобільного застосунку для аутсорсингової команд...
 
Large drupal site builds a workshop for sxsw interactive - march 17, 2015
Large drupal site builds   a workshop for sxsw interactive - march 17, 2015Large drupal site builds   a workshop for sxsw interactive - march 17, 2015
Large drupal site builds a workshop for sxsw interactive - march 17, 2015
 
Pat Farrell, Migrating Legacy Documentation to XML and DITA
Pat Farrell, Migrating Legacy Documentation to XML and DITAPat Farrell, Migrating Legacy Documentation to XML and DITA
Pat Farrell, Migrating Legacy Documentation to XML and DITA
 
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint Solutions
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint SolutionsZero to 365 in One Hour: Processes and Tools for Effective SharePoint Solutions
Zero to 365 in One Hour: Processes and Tools for Effective SharePoint Solutions
 
Open Source Lessons from the TODO Group
Open Source Lessons from the TODO GroupOpen Source Lessons from the TODO Group
Open Source Lessons from the TODO Group
 
Software development process for outsourcing team
Software development process for outsourcing teamSoftware development process for outsourcing team
Software development process for outsourcing team
 
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovix
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovixapidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovix
apidays LIVE Paris 2021 - Who writes the Docs? by Laura Vass, Pronovix
 
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...
Navigating the mess of a Shared Network Drive Migration to SharePoint - SPS B...
 
Oscon 2016: open source lessons from the todo group
Oscon 2016: open source lessons from the todo groupOscon 2016: open source lessons from the todo group
Oscon 2016: open source lessons from the todo group
 
Maintainable Machine Learning Products
Maintainable Machine Learning ProductsMaintainable Machine Learning Products
Maintainable Machine Learning Products
 
A simple test paper from Chen
A simple test paper from ChenA simple test paper from Chen
A simple test paper from Chen
 

Kürzlich hochgeladen

The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...
The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...
The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...Aggregage
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Will Schroeder
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Websitedgelyza
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfDaniel Santiago Silva Capera
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesMd Hossain Ali
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?IES VE
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintMahmoud Rabie
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...DianaGray10
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxMatsuo Lab
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-pyJamie (Taka) Wang
 
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDE
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDEADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDE
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDELiveplex
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1DianaGray10
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioChristian Posta
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxUdaiappa Ramachandran
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXTarek Kalaji
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfDianaGray10
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAshyamraj55
 

Kürzlich hochgeladen (20)

The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...
The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...
The Data Metaverse: Unpacking the Roles, Use Cases, and Tech Trends in Data a...
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Website
 
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdfIaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
IaC & GitOps in a Nutshell - a FridayInANuthshell Episode.pdf
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership Blueprint
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptx
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-py
 
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDE
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDEADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDE
ADOPTING WEB 3 FOR YOUR BUSINESS: A STEP-BY-STEP GUIDE
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and Istio
 
Building AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptxBuilding AI-Driven Apps Using Semantic Kernel.pptx
Building AI-Driven Apps Using Semantic Kernel.pptx
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBX
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
 

DocOps: Documentation at the Speed of Agile

  • 1. DocOps Documentation at the Speed of Agile for Keep Austin Agile 2016
  • 2. 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
  • 4. What are Agile Docs? or Don’t we get to stop doing docs? 1
  • 5. “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
  • 6. True: Agile means we write less.
  • 7. “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
  • 8. Documentation = Internal to project development Project plans Requirements Functional specifications Design specifications Feature proposals Reference artifacts Test: “Will customers ever see it?”
  • 9. 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
  • 10. In Agile docs, where are the writers? ◎ Who has writers on scrum teams? ◎ If not, where do you put them? ◎ Regardless, they are pigs
  • 11. 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
  • 12. 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
  • 13. “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?
  • 14. What is “DocOps”? DevOps for documentation or How to always be shippable 2
  • 15. 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
  • 16. 5 elements of DocOps* 1 Agility 2 Continuous updates 3 Collaborative authoring 4 Content aggregation 5 Customer integration * https://docops.ca.com
  • 17. 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
  • 18. 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
  • 19. CA case study DocOps platform that is a "wiki++" ◎ friendly wiki (Confluence) + ◎ powerful extensions: ◉ standardization (editing) ◉ publication ◉ translation
  • 21. 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
  • 22. 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.
  • 23. 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
  • 24. 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)
  • 25. How Do I Build It? Getting there from where you are 3
  • 26. Where to start? ◎ Tool and platform choices ◎ Example stacks and outputs ◎ Practical requirements (4 areas) ◎ Working with what you’ve got ◎ Being Agile
  • 27. 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
  • 28. 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)
  • 29. “ DocOps out of the box? Author-It MindTouch ZenDesk?
  • 30. “ {handy source format} + {automated transform} + {version control} [ + {translation management} ]
  • 31. 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
  • 32. 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
  • 33. 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
  • 34. 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
  • 35. 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
  • 36. “ 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
  • 37. “ 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
  • 38. “ 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
  • 40. Credits Special thanks to all the people who made and released these awesome resources for free: ◎ Presentation template by SlidesCarnival ◎ Photographs by Unsplash
  • 41. 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