Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.
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.c...
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 collabor...
True: Agile means we write less.
“Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collabor...
Documentation = Internal
to project development
Project plans
Requirements
Functional
specifications
Design specifications...
Documentation is
part of “software”,
regardless of source
“software” = CX* deliverable
*Customer Experience
CX = GUI + API...
In Agile docs,
where are the writers?
◎ Who has writers on scrum teams?
◎ If not, where do you put them?
◎ Regardless,
the...
New Role:
Writer as Super Pig
❏ Invite and expect them to act as
pig on team(s)
❏ Most important:
co-owner of info product...
Status
Release Note
Gotta Make it Happen
Definition of Done
= Ready to ship:
❏ Release Note
❏ Critical facts
❏ Happy path
...
“Yeah, but what about....”
Docs lagging
a sprint?
Remember:
1. Lean doc
2. Super pig
3. Def of done
Hardening
sprints to d...
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...
5 elements of DocOps*
1 Agility
2 Continuous updates
3 Collaborative authoring
4 Content aggregation
5 Customer integratio...
The Key Three
1 Agility
Respond to code changes right away
(minutes, not months)
2 Continuous updates
Push fixes immediate...
Extra Credit:
4 Content aggregation
Pull together all content, from sales and
marketing through support and training
5 Cus...
CA case study
DocOps platform that is a
"wiki++"
◎ friendly wiki (Confluence) +
◎ powerful extensions:
◉ standardization (...
CA’s Immediate Results
25% word count savings [lean]
(via consolidation)
25% efficiency gains [automation]
(from trimming ...
CA’s DocOps Pieces
Collaborative
authoring and
aggregation:
Atlassian
Confluence
Doc production:
k15t Scroll,
1. Acrolinx
...
Success Criteria
1. Automatic outputs
◉ No-touch builds
◉ No-touch delivery
2. Single-sourcing
◉ Across products (reuse)
◉...
Examples of doc
automations
Hourly builds and
refresh of intranet
Script to parse object
code into doc XML
Script to find ...
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...
Tool stacks - local
Word source + Doc-To-Help build
FrameMaker/Word source + RoboHelp build
FrameMaker/Word source + WebWo...
New: Cloud Tools,
OSS, & “beta-ware”
ClickHelp w/ export API
Confluence Cloud (exports?)
HelpIQ, Paligo (automation?)
Read...
“
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, hig...
Agile Authoring
= easy to:
◎ Import rich
content created
elsewhere (legacy)
◎ Create topics
◎ Update topics
◎ Release (for...
Agile Response
= easy to:
◎ Trace and and
autolink with
support cases
and dev issues
◎ Support
involvement
◉ Find
◉ Reques...
Agile Self-Service
= easy to:
◎ Single-sign-on with
existing product
and support sites
◎ Search across all:
docs, blogs, f...
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
Prune & rank
requirements
Scorecard of your Agile doc reqs,
ranked by urgency, to compare options
● Goal: Don’t compar...
“
2
Love the one
you’re with
Let your environment, legacy situation,
and IT resources set direction
● Tip: Product bundles...
“
3
Working code
over plan
Do a proof-of-concept, then pilot
project, and keep tweaking
● Be agile! Resist pressure to pro...
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 b...
Presentation design
This presentation uses the following typographies and colors:
◎ Titles: Nixie One
◎ Body copy: Varela ...
DocOps: Documentation at the Speed of Agile
Nächste SlideShare
Wird geladen in …5
×

DocOps: Documentation at the Speed of Agile

2.145 Aufrufe

Veröffentlicht am

Presented at Keep Austin Agile 2016: How to we make documentation "Agile", given the Agile Manifesto? How do you get into the Definition of Done? What does "DocOps" mean, in the simplest and broadest terms? What should your requirements be for a DocOps transformation, and how do you find a tool stack that fits them? Where do you start, and how do you escape a waterfall reengineering of your legacy docs?

Veröffentlicht in: Technologie
  • Hi, Mary. Loved the video interview and I've been pushing adoption of a DocOps mindset in my organization as well. I, too, believe that the technical communication game is changing drastically and quickly. Technical writers must evolve into new roles revolving around information architecture, metadata, quality, and governance while the content is contributed by everyone. Fight the good fight!
       Antworten 
    Sind Sie sicher, dass Sie …  Ja  Nein
    Ihre Nachricht erscheint hier

DocOps: Documentation at the Speed of Agile

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

×