DITA and Agile are Made for Each Other by Keith Schengili-Roberts, IXIASOFT DITA Specialist. Presented at CMS/DITA North America 2016 in Reston, Virginia. Agile software development makes specific demands on documentation teams, whose content creators now need to be more nimble, describe features in a piece-meal fashion, and report on their progress in an effective way. The topic-based structure of DITA is ideally suited to these needs. Keith Schengili-Roberts (also known as “DITAWriter”) focuses on how DITA-based content is the optimal way of working in an Agile environment, enabling content creators to effectively meet the demands of short sprint cycles, measure content output for Scrum meetings, and how to become a pig rather than staying a chicken (yes, seriously). Keith also looks at several case studies of DITA-using documentation groups working within an Agile environment. If you are wondering about what the impacts are of working with Agile or are simply looking to optimize your DITA-based documentation processes, come to this presentation! What can the audience expect to learn? Keith expands upon the material that was touched upon during the Best Practices conference on the same subject, including information based on subsequent interviews with clients and other content creators who are using DITA in an Agile environment. He provides information on how others are using DITA in this scenario and emerging best practices within it. Keith has found that many content creators using DITA are looking to move to an Agile environment—particularly if they work for a software firm. The ideas presented here serve as an introduction on what to expect. Even those who do not fit this scenario may find some of the ways and processes used by DITA-using doc groups in an Agile team to be beneficial.

1. DITA and Agile are
Made for Each Other
Keith Schengili-Roberts
DITA Information Architect, IXIASOFT

2. Agenda
• Introduction
• Documentation Management
 History / Beginnings
 Waterfall and Agile
 Flavors of Agile
• DITA and Agile
 Popularity and growth of DITA and Agile
 How DITA Helps Technical Writers Working in an Agile
Environment
 Specific examples / Case studies
• Q/A

3. Who’s This Guy?
• Keith Schengili-Roberts
What I do:
• DITA evangelist
• Liaison with OASIS; on DITA
Adoption and Technical
Committees, also aiding in
relaunch of dita.xml.org website
• Industry researcher
• Also lecturer on Information
Architecture at the University of
Toronto
• Have 10+ Years of experience with
DITA XML

4. Am Also “DITAWriter”
• Industry blog started ~5 years ago
• Just over 195,000 hits
• Have regularly updated info on
DITA Conferences, DITA Books,
DITA CMSes, DITA Editors, other
DITA Tools, and DITA Consulting
Firms
• Recent updated “Companies
Using DITA” listing, now with over
600 firms
• News and views on DITA use
• Also features interviews with
those making a difference in the
world of DITA

5. Another Thing People Might Not Know About Me…
• I have always had an interest
in Management studies and
hold a Masters in Public
Administration (MPA)
 Have been exposed to many
management trends over the
years, and teach Lean
techniques in my IA course
 Am particularly interested in
effective management of
documentation groups
• Since summer 2015 have been interviewing various tech
writers and managers about their Agile + DITA experiences

6. Beginnings of Technical Writing
• There has always been a
need to instruct people on
how to do practical things,
including:
 Ancient Egyptian medical and
mathematical texts
 Certain Ancient Greek
philosophical works
 Roman engineering texts
 Medieval instructional
publications
• In English, the first instruction
manual is widely considered to be
Chaucer’s “A Treatise on the
Astrolabe”

7. Technical Writing as a Cottage Industry
• Technical writing as we know it
started in early 20th century
 Ford Model T manual (1919) is a
good example of this
 Joseph Chapline wrote first
computer manual for BINAC (1949)
• Was often done by a single person,
often a SME
• They tended to idiosyncratic and
often one-offs
• Thinking was that you didn’t need
to “manage” a single person writing
content

8. Technical Writing and DTP
• Growth of technical writing developed
(primarily) alongside growth of software
industry
• Desktop Publication Programs made it
possible to writers to create documents
from beginning to end
 This also opened up possibilities for
collaboration
• Initial attempts were awkward, often
involved sneaker-net (passing a floppy disc
with content to another writer)
 Basically one isolated writer
handing content over to
another

9. The Need for Documentation Management
• As volume of content
grew, collaborative
documentation practices
became a necessity
 No longer one writer=one
document, but many
writers=one document /
many documents
• Getting writers to
collaborate has been
described as being akin to
“cat herding”

10. Focus on Managing Documentation Processes
• As documentation teams grew,
was a real need to coordinate
tech writing projects
• JoAnn Hackos’ Information
Development (2006) was the
first book to explore subject of
documentation management
 And the book does talk about Agile:
“It is most important for information
project managers to recognize that
traditional project management
methods must be adapted to agile
projects. It may be impossible, for
example, to produce traditional
documentation at all.” (pg. 342)

11. Waterfall Management and Technical Writing
• The waterfall model also began in the
software development realm, first
described in detail in early 1970s
• Sequential design process, starting
with analysis and ending with
maintenance (updates)
• Technical writing typically fell between
Coding and Testing phases, well after
Requirements and Design phases
 “Just document what’s there (or will be
there).”
 Majority of documentation teams out
there still follow this model (and there’s
nothing necessarily wrong with that)
A certain young tech writer at
Delrina, circa mid-1990s
Pre-Agile, definitely Waterfall

12. Problems with Waterfall Management
• Waterfall-based software
projects were prone to failure
 In 1995 DoD found that of $35.7
billion spent by the organization
on software, only 2 percent of
the software was usable as
delivered, and that 75% was
either never used or was
cancelled prior to delivery.
• Waterfall does not deal with
changing/adapting to customer
needs gracefully

13. Agile is Not for Every Business Environment
• Agile thrives in environments where short release
cycles are possible; appears to be rare in highly
regulated environments or heavy machinery for
example
 Have found one case of Agile being used in Pharma, though only
after and their software division successfully adopted it
 I have found instances of Agile + DITA in Medical Devices, Heavy
Machinery sectors, but in these cases it was by the software
divisions at these firms
• In environments where business factors are pushing for
rapid change in product development, Agile methodologies
are likely to be introduced

14. Where Agile Thrives
• In general, software is in the
shaping quadrant of industry
types, where environment is
unpredictable but can be
“shaped”
• Rapid testing of releasable
product helps shape the
market/user’s expectations;
Agile approach makes this
possible
• Need an equally “agile” way to
manage documentation

15. Evolution of DITA within Technical Writing
• DITA is arguably the natural
evolution of the need for
many writers to work and
reuse content more efficiently
• Similarly, Agile can be seen
as a way for fast-moving
development teams to meet
the needs of their customers
 The two methodologies
compliment each other (when
done right)

16. ISO Standard for Agile Documentation
• ISO/IEC/IEEE 26515:2011-
12 is an ISO standard
describing how to develop
user documentation in an
Agile environment
• Neatly outlines everything
you need to know about
Agile + documentation
• Dates to 2012, and there is
a drive to update it

17. Similarities Between Agile and DITA Sectors
• Though not a direct correspondence, there is at least some
cross-over between DITA- and Agile-using firms
Source: DITAWriter.com
Source: VersionOne 10th Annual State of Agile Report.
© 2016 VersionOne Inc. All rights reserved.

18. DITA is Clearly Popular Among Agile Teams
• DITA is the most popular form of structured content used
by Agile teams (data from LinkedIn):

19. Development of Agile
• Agile Manifesto written in 2001:
• A clear difference from the traditional waterfall approach to docs

20. There Are Many “Flavors” of Agile
• There are many different
techniques and approaches that
are Agile or allied with Agile
• They include (but are not limited
to):
 Scrum
 Kanban
 eXtreme Programming (XP)
 Lean

21. Scrum and Kanban
Scrum:
• Focuses on emerging
requirements and
responding quickly to
change
• Includes daily meetings
held by Scrum Master,
plan Sprints for work to
be done in a short
timeframe
• Review what team
members have done,
what they will do and
whether there are
impediments to progress
Kanban:
• Card-based “Just in
Time” methodology
originally used by
manufacturers (Toyota)
• Kanban team focuses
on work in progress;
when done, pulls next
card from top of
backlog
• A goal is to optimize
start to finish cycle
time, teams make
themselves and their
work more efficient
Standup Scrum Meeting
Kanban Board

22. eXtreme Programming and Lean
eXtreme Programming
(XP):
• Activities: coding,
testing, listening,
designing
• Assume simplicity,
embrace change,
rapid feedback
• multiple short
development cycles,
emphasis on feedback
on code (unit tests)
and customer
(acceptance tests);
this includes
documentation
Lean:
• Seeks to eliminate
things that do not add
value to customer
(“muda”, a type of
waste)
• Continuous
improvement, short
iteration cycles,
deliver as fast as
possible

23. Which Agile Methodologies are Used the Most?
• While Scrum is clearly dominant, hybrid approaches are also common
Source: VersionOne 10th Annual State of Agile Report.
© 2016 VersionOne Inc. All rights reserved.

24. Agile in Technical Documentation
• I have been interviewing tech doc
members at various companies who
said they were Agile.
• But when I ask them about their
processes they are often in fact:
 Largely Waterfall-based, or
 Do not want to be perceived as not
being Agile (whatever that is), or
 “Rest of company is Agile so we must
be too” (i.e. “Agile by osmosis”), or
 Transitioning to some flavor of Agile.
• I found “pseudo-Agile” doc teams to be surprisingly common.

25. Why DITA + Agile = A Great Partnership!
DITA Agile
Topic-based approach Incremental development; can update
topics as required; self-contained
Task topics User stories; content is focused
squarely on what user needs to do
Individual topics can be counted; in a
CMS workflow can be measured
Need to track development progress;
easy to demonstrate progress
Best practice of minimalism Document only what needs to be
documented; Keep It Straight and
Simple (KISS) and Keep It Light (KIL);
Reduces waste
Reuse improves content consistency Continuous feedback from developers
and users
Iterative publication to multiple formats
on demand
No holdup for incremental product
releases

26. Agile Implications for Documentation Processes
• Content creators have to
work more closely with
developers
• Documentation may support
broader communication,
such as between teams,
customers, audit process,
etc.
• Work cycles are faster,
feedback more critical
• Efficient documentation tools
make things easier (single
sourcing, structured content,
CMS)
Following slides examine
some common
approaches I ran across
various DITA + Agile
teams

27. What Agile Means in Practice for Tech Doc Teams
• Work more closely with developers
 Tech writer assigned to work with one or more
development teams; does regular reports on progress
(Scrum with Stand-up meetings, Kanban priorities, etc.)
• Provide early feedback on product
 Through active use of product tech writers often become
advocate for users; helps to define realistic user stories
• Constant change/iterations of content
 Incremental releases, and a change of focus from
“document everything” to “document only what the user
needs”

28. • Content reuse: “write once,
use many”
 No need to re-write what
already exists
 Content consistency
 Single-sourcing is built in
Agile and Content Reuse in DITA
“[DITA] handles the reuse of small information chunks brilliantly. My
engineers reused functions and objects constantly as they developed new
features. I found it invaluable to be able to conref (reuse by reference)
previously written tables, sections, paragraphs, procedure steps, etc..
During that last long night at the end of sprint I was never too proud to
reuse available writing.”
– Stan Doherty

29. A DITA Advantage: Separation of Form and Content
• Time is spent writing rather
than formatting
 Separating content from
formatting saves considerable
time
In an informal survey done on a team of technical writers using
popular DTP software, roughly half of their time was spent
formatting content. That time can now instead be put towards
writing more Agile content in a structured XML environment

30. Tech Writers Become Part of Feedback Loop
• Tight integration of tech writers
with development team opens
possibilities for early feedback
on product development
“The goal of technical
communicators is not to explain
confusing product features, but to
prevent them.” – Tim Grantham,
2008

31. Separate Content Management from Authoring
• Ideally IA / Manager are several iterations ahead
and planning out topics to be authored
 Map with topics created, writers “fill in the blanks”
 Helps to emphasize that writers need to be embedded
with development + QA
 Example of creating stub topics within a map in the IXIASOFT DITA CMS

32. Only Document What is Necessary
• Not only based on feedback from developers, but
also from users
• Fits with minimalist writing principles; ditto Lean
• When possible, track online usage from published
docs, and prioritize user-favored content
 One interesting example: UI-related content “how to”
style content is reduced and UX is improved by writer
feedback, ensuring UI is more usable

33. User Stories and DITA Tasks
• Scrum-based Agile often
calls upon User Stories to
craft development
• Often take form of various
procedures that users will
want to accomplish; this fits
DITA’s topic types nicely
“DITA allows correlating user stories to specific procedures
much easier than other less granular formats. This can be
utilized in some pretty creative ways to apply principals of
continuous integration, and testing to documentation.”
- Casey Jordan

34. User Stories and DITA Tasks (cont.)
• Possible Agile best practice
for writing tasks:
 Instead of writing a concept to
be followed by a task,
encapsulate that concept as
the context for a task instead
 Depending on scenario,
describe expected outcomes
for individual steps/conclusion
 Use concept topics to link
between tasks
Concept
Task
Task
Context

35. Epics and Audiences
• “Epics” are a collection of related user stories that
comprise the complete workflow for a type of user
• From a DITA standpoint, epics can be used to help
refine conditional processing for audience
 User types may change during development; the “agility”
and flexibility of DITA makes it possible to change quickly

36. Short Descriptions Direct Users to Content
• Writing short description for
DITA topics is already
considered a best practice
 Arguably more so for Agile-
based content, as it provides a
means of progressive
disclosure as to the relevancy
of content to users
 Can be similar in intent to a
user story: “User x can do y
based on z”

37. DITA 1.3 Troubleshooting and Agile
• DITA 1.3 adds troubleshooting
as a new topic type
• Designed to provide specific
solutions to scenarios that are
likely to arise, and how to solve
them
• Will be welcomed by Agile
writers who are looking for a
troubleshooting option for user
stories and where a task may
not be an appropriate solution
“The troubleshooting pattern
of condition > cause >
remedy is essentially a
scenario.”
- Bob Thomas

38. DITA Topic Granularity and Measurability
• DITA’s topic-based approach
also makes it easy to measure
content
 Within a CMS it is also possible to
track how “done” topics within a
map are
• DTP-based docs much harder
to track due to lack of this level
of granularity
“Our project managers could track progress of
documentation deliverables within our DITA-based
CMS on a daily basis.”
- Jason Owen

39. Feedback is Part of Agile
• Documentation feedback is
a developer requirement
under Agile
• Using DITA, turnaround of
topic-based review with
SMEs much reduced
 SMEs can provide
feedback in a more timely
manner
“Developers would review topics on the spot in the Agile
team room. Agile also left no room for procrastination, so
this was an easy way for them to check this off their own
task list.” - Jason Owen

40. Common Problems Encountered by Tech Doc Teams
Problem #1: Agile will not solve
understaffed tech doc teams
Symptoms:
• Writers cannot attend stand-
up meetings due to scheduling
conflicts
• Writers perennially falling
behind on assigned topics to
write
A good Agile process manager will recognize the problem
and either throttle back work or bolster effort for new hires

41. Common Problems Encountered by Tech Doc Teams
Problem #2: Need to make
documentation “glue” for publications
 Applies to cases where a full
manual is expected
 High-level introductory or
conceptual material not typically
accounted for in a sprint
 There’s still a need to answer the
“why would you use this?” type of
question
Solution is to recognize this need up front, and allow for it in
the overall documentation plan

42. An Example of How DITA Can Enable Agile
Lean methodology employed at AMD;
early on localization was a focus:
• Under old toolchain could only
localize software (with 1 month
cadence) once every 6 months
• Using DTP-based processes, it was
costly, slow and process did not
allow for feedback
DITA + CMS made localizing on a
monthly cadence possible
• Demonstrated considerable costs
savings
• Localization staff could focus on
quality and provide developers with
feedback
Localization Process Pre-Lean:
Localization Process After Lean + DITA + CMS:

43. DITA + Agile Case Study #1
• Semiconductor industry example:
 Prior to move to DITA, used traditional
Waterfall method
 A “doc build” with their DTP program could
take as long as a day; longer if it crashed
 DITA opened up possibility of moving tech
docs to a more Agile approach
• Results:
 Considerable time saved by no longer
dealing with formatting issues
 Topic-based review process has greater
uptake with SMEs than “here’s a whole
finished manual for you to read”
 Can now do daily “publication builds” of
their content; early access given to tier 1
clients

44. DITA + Agile Case Study #2
• Software sector example:
 Writers were already embedded in
software development teams, but
existing DTP tools meant they were
always trying to catch up
 Lack of granularity meant that DTP-
produced documents were hard to track
• Results:
 DITA + CMS means that writers now
have the time to both create content
and to participate fully in the Agile
process
 Per topic progress reports now
possible; now a regular part of scrum
meetings, and can even be done on-
the-fly on request

45. A Tale About Commitment in Agile
Pigs produce product and are fully committed;
chickens are involved and engaged but not
necessarily committed. Content creators often
start as chickens, but become pigs as developing
content becomes part of the product. Which are you?

46. Some Parting Thoughts
“DITA did not directly enable or guarantee
effective documentation in an Agile/SCRUM
environment, but it sure saved my bacon in
supporting multiple scrum teams with variant
definitions of done.”
- Stan Doherty
“Agile development goes hand in hand with
topic writing, and I think this is why it’s a
perfect match for DITA. I love working in
Agile! It makes my life as a writer much,
much easier.”
- Nathalie Laroche

47. Q/A
• Blog on www.ixiasoft.com
• Twitter: @IXIASOFT and @KeithIXIASOFT
• IXIASOFT DITA CMS Users LinkedIn group
• OASIS DITA Adoption Committee articles
• Member of OASIS DITA Technical Committee
Time for Q/A!