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?
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
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
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?
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
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
20.
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
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